Nginx Configuration Guide

This comprehensive guide will help you configure Nginx to work seamlessly with Ltranslate for automatic website translation.

Prerequisites

• Nginx 1.15+ installed on your server
• Active Ltranslate account with API key
• Root or sudo access to server configuration
• Basic understanding of Nginx configuration

Basic Configuration

1. Obtain API Key

First, get your API key from the Ltranslate dashboard:

# Sign up at https://ltranslate.cn
# Create a new website project
# Copy your API key from project settings

2. Configure Nginx

Open your Nginx configuration file and add the following configuration:

server {
    listen 80;
    server_name your-domain.com;
    
    # Original content handler
    location / {
        proxy_pass http://backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
    
    # Translation handler
    location ~ ^/(zh-cn|ja|ko|es|fr|de)/ {
        proxy_pass https://engine.ltranslate.cn;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header api-key "YOUR_API_KEY";
        proxy_set_header source-lang "en";
        proxy_set_header target-lang $1;
        proxy_set_header url "https://$host$request_uri";
    }
}

3. Reload Nginx

# Test configuration
sudo nginx -t

# Reload Nginx
sudo systemctl reload nginx

Advanced Configuration

Language Detection

Automatically detect user's preferred language and redirect:

server {
    listen 80;
    server_name your-domain.com;
    
    # Language detection based on Accept-Language header
    set $target_lang "";
    
    if ($http_accept_language ~* "zh-CN") {
        set $target_lang "zh-cn";
    }
    
    if ($http_accept_language ~* "ja") {
        set $target_lang "ja";
    }
    
    if ($http_accept_language ~* "ko") {
        set $target_lang "ko";
    }
    
    # Default to English if no match
    if ($target_lang = "") {
        set $target_lang "en";
    }
    
    location / {
        proxy_pass http://backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header target-lang $target_lang;
    }
}

Caching Configuration

Configure caching to improve performance and reduce API calls:

proxy_cache_path /var/cache/nginx/ltranslate levels=1:2 keys_zone=ltranslate_cache:10m inactive=60m;

server {
    # ... other configuration ...
    
    location ~ ^/(zh-cn|ja|ko|es|fr|de)/ {
        proxy_cache ltranslate_cache;
        proxy_cache_key "$scheme$request_method$host$request_uri";
        proxy_cache_valid 200 302 60m;
        proxy_cache_valid 404 1m;
        
        proxy_pass https://engine.ltranslate.cn;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header api-key "YOUR_API_KEY";
        proxy_set_header source-lang "en";
        proxy_set_header target-lang $1;
        proxy_set_header url "https://$host$request_uri";
        
        add_header X-Cache-Status $upstream_cache_status;
    }
}

SSL Configuration

Configure SSL for secure connections:

server {
    listen 443 ssl http2;
    server_name your-domain.com;
    
    ssl_certificate /path/to/your/cert.pem;
    ssl_certificate_key /path/to/your/private.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512:ECDHE-RSA-AES256-GCM-SHA384;
    
    # ... translation configuration ...
}

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;
}

Performance Optimization

Connection Pooling

upstream ltranslate_backend {
    server engine.ltranslate.cn:443 max_fails=3 fail_timeout=30s;
    keepalive 32;
}

server {
    # ... other configuration ...
    
    location ~ ^/(zh-cn|ja|ko|es|fr|de)/ {
        proxy_pass https://ltranslate_backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        
        # ... other headers ...
    }
}

Rate Limiting

# Rate limiting for translation requests
limit_req_zone $binary_remote_addr zone=translate_zone:10m rate=10r/s;

server {
    # ... other configuration ...
    
    location ~ ^/(zh-cn|ja|ko|es|fr|de)/ {
        limit_req zone=translate_zone burst=20 nodelay;
        
        # ... proxy configuration ...
    }
}

Troubleshooting

Common Issues

Debug Mode

Enable debug logging for troubleshooting:

error_log /var/log/nginx/translate_error.log debug;

server {
    # ... other configuration ...
    
    location ~ ^/(zh-cn|ja|ko|es|fr|de)/ {
        proxy_pass https://engine.ltranslate.cn;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header api-key "YOUR_API_KEY";
        proxy_set_header source-lang "en";
        proxy_set_header target-lang $1;
        proxy_set_header url "https://$host$request_uri";
        proxy_set_header debug "true";
    }
}

Examples

WordPress Site Example

server {
    listen 80;
    server_name wordpress-site.com;
    
    # WordPress original content
    location / {
        try_files $uri $uri/ /index.php?$args;
    }
    
    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }
    
    # Translation for WordPress
    location ~ ^/(zh-cn|ja|ko)/ {
        proxy_pass https://engine.ltranslate.cn;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header api-key "YOUR_API_KEY";
        proxy_set_header source-lang "en";
        proxy_set_header target-lang $1;
        proxy_set_header url "https://$host";
    }
}