Localization

Run a Kubernetes deployment in one language, or in several languages on their own subdomains.

The web service picks the interface language from the settings below, per request from the host name the browser used. The languages and the settings are described in Localization.

Service	web, in every Ayakaleaf Pro pod; read when web starts
Network	one host name per language, all routed to Ayakaleaf Pro
Periodic jobs	none

One language

  OVERLEAF_SITE_LANGUAGE: zh-CN

kubectl apply -f 30-config.yaml
kubectl -n overleaf rollout restart deployment/overleaf     # or statefulset/overleaf

Several languages on subdomains

1. Route every language host to Ayakaleaf Pro

   Add a DNS name per language and route them all to Ayakaleaf Pro with a certificate that covers them, for example *.example.com. Your ingress or load balancer must pass the Host header unchanged, which ingress-nginx and HAProxy do by default.

   Users must reach the language hosts on the standard ports (https://cn.example.com, not https://cn.example.com:30443): Ayakaleaf Pro compares the host without the port.

2. ConfigMap

   30-config.yaml (additions)

     OVERLEAF_SITE_URL: https://www.example.com
     COOKIE_DOMAIN: .example.com
     OVERLEAF_LANG_DOMAIN_MAPPING: '{"www": {"lngCode": "en", "url": "https://www.example.com"}, "cn": {"lngCode": "zh-CN", "url": "https://cn.example.com"}}'
   

   COOKIE_DOMAIN lets the login cookie work on every language host. Put the JSON in single quotes. Invalid JSON in OVERLEAF_LANG_DOMAIN_MAPPING stops every service of the pod at startup, so check kubectl -n overleaf get pod after the restart.

Several replicas

The language comes from the host name of each request, so it does not depend on the replica. The load balancer’s sticky cookie is set per host name unless you give it a domain, so switching language can move a user to another replica; their session is in Redis and stays valid.

Tested on Kubernetes

On Kubernetes 1.37 behind HAProxy, with OVERLEAF_LANG_DOMAIN_MAPPING mapping the site’s host to English, a de. host to German and an fr. host with the NodePort :30081 to French: the site’s host showed English, the de. host German, and the fr. host with the port fell back to English, as described above.