Skip to content

troubleshooting.md

Latest commit

 

History

History
123 lines (85 loc) · 3.97 KB

troubleshooting.md

File metadata and controls

123 lines (85 loc) · 3.97 KB

Troubleshooting

Common issues and their solutions when working with LocaleSync.

SSL certificate errors during translation

Symptom: locale-sync translate or locale-sync sync --translate fails with SSL: CERTIFICATE_VERIFY_FAILED or requests.exceptions.SSLError.

Cause: Corporate proxy (Zscaler, Netskope, etc.) intercepts HTTPS traffic to Google Translate and uses its own CA certificate that Python's requests library doesn't trust.

Fix - find and export your corporate CA bundle:

macOS / Linux 
# macOS - export system certificates (includes Zscaler CA)
security find-certificate -a -p \
  /Library/Keychains/System.keychain \
  /System/Library/Keychains/SystemRootCertificates.keychain \
  > ~/combined-ca-bundle.pem

# On Linux, the CA bundle is usually already available:
#   /etc/ssl/certs/ca-certificates.crt          (Debian/Ubuntu)
#   /etc/pki/tls/certs/ca-bundle.crt            (RHEL/Fedora)
# If your proxy adds its own CA, ask your IT department for the .pem file
# and append it: cat corporate-ca.pem >> ~/combined-ca-bundle.pem

# Tell Python / requests to use it (add to ~/.zshrc or ~/.bashrc to persist)
export SSL_CERT_FILE=~/combined-ca-bundle.pem
export REQUESTS_CA_BUNDLE=~/combined-ca-bundle.pem

# Now translation works
locale-sync sync --source en --translate --target de,fr,es locales/
Windows (PowerShell) 
# 1. Export corporate CA certificate
# Ask your IT department for the corporate CA .pem file, or export it from
# certmgr.msc → Trusted Root Certification Authorities → Certificates
# Right-click → All Tasks → Export → Base-64 encoded X.509 (.CER)
# Save as: %USERPROFILE%\corporate-ca-bundle.pem

# 2. Configure SSL trust (add to your PowerShell profile to persist)
$env:SSL_CERT_FILE = "$env:USERPROFILE\corporate-ca-bundle.pem"
$env:REQUESTS_CA_BUNDLE = "$env:USERPROFILE\corporate-ca-bundle.pem"

# 3. Now translation works
locale-sync sync --source en --translate --target de,fr,es locales/

Tip: To make permanent: [System.Environment]::SetEnvironmentVariable("SSL_CERT_FILE", "$env:USERPROFILE\corporate-ca-bundle.pem", "User")

How it works: LocaleSync automatically tries to export macOS system keychain certificates (which include corporate proxy CAs) before making any translation request. On macOS, this usually "just works" without manual configuration. On Windows and Linux, set SSL_CERT_FILE explicitly.

SSL errors during pip install

Symptom: pip install -e ".[dev]" fails with SSL: CERTIFICATE_VERIFY_FAILED or similar.

Cause: Same corporate proxy issue - pip also needs the CA bundle.

Fix: Set SSL_CERT_FILE and REQUESTS_CA_BUNDLE before running pip (see above), then:

pip install --upgrade pip setuptools
pip install -e ".[dev]"

Proxy configuration

LocaleSync's Google Translate backend uses requests, which automatically respects standard proxy environment variables:

# macOS / Linux
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1
# Windows (PowerShell)
$env:HTTP_PROXY = "http://proxy.example.com:8080"
$env:HTTPS_PROXY = "http://proxy.example.com:8080"
$env:NO_PROXY = "localhost,127.0.0.1"

No additional LocaleSync configuration is needed.

Translation fails with RequestError

Symptom: Translation fails after 3 retries with a RequestError.

Cause: Google Translate's free API may be rate-limiting or blocking your IP.

Fix:

  • Check your internet connectivity.
  • If behind a proxy, ensure proxy env vars are set (see above).
  • Wait a few minutes and retry - Google's rate-limit window is short.

Server won't start - address already in use

# Find and kill whatever is using the port
lsof -i :8083 -t | xargs kill -9    # macOS / Linux

# Or use a different port
locale-sync serve --port 9083