Translations - Degoog Docs

How it works

The server figures out your locale on every request. It gathers all the translations for that specific locale from your extensions, serializes them into window.__DEGOOG_T__, and injects the result straight into the page before it ever reaches your browser. We do not load any locales on the client side.

We resolve your locale in this order:

The DEGOOG_I18N environment variable. If you set this, it forces a specific locale for every single request.
Your browser Accept-Language header. This is matched against the available locale files. We look for the exact tag first, then fall back to the language only, and finally default to en-US.

On the client, calling window.scopedT("namespace") gives you a t(key) function scoped to a specific namespace inside window.__DEGOOG_T__. The core application uses scopedT("core"). Your extensions automatically receive their own unique namespace.

For the HTML output returned by your plugins and built in commands, strings are translated on the server using the {{ t:key }} syntax:

return {
  html: `<p>{{ t:plugin-myname.some-string }}</p>`
};

You can interpolate variables by passing comma separated names right after the key. These map to {{ varname }} template placeholders in your rendered output so the client side template engine can substitute them later on:

{ "plugin-myname.found": "Found on: {sources_text}" }
`{{ t:plugin-myname.found, sources_text }}`

Locale file format

Every locale file is just a plain JSON object. You separate your keys with dots and nest them into objects. The values are strings and can contain named placeholders wrapped in {curly braces}. Please do not rename these placeholders, although you are free to reorder them to fit your language structure.

{
  "plugin-weather": {
    "codes": {
      "0": "Cielo sereno",
      "unknown": "Sconosciuto"
    },
    "usage": {
      "needCityLine1": "Uso: <code>!weather <città></code>"
    }
  }
}

Locale codes follow the BCP 47 standard. The core settings page and default theme use the full tag like en-US or fr-FR. Built in commands and third party plugins use the short language code like en or fr.

Core locale files

Here are the files you need to create if you want to add a new language to the core application. Each one has an English original you can base your translation on. Make sure you only change the values and never the keys.

src/locales/<locale>.json: This covers the Settings page, including all tabs, modals, store UI, and errors. You can copy this from src/locales/en-US.json. This uses the full locale tags like en-US or fr-FR.
src/public/themes/degoog-theme/locales/<locale>.json: This handles the Home page and search results page, including the title, search button, tab labels, and footer links. Copy it from …/degoog-theme/locales/en-US.json. This also uses full locale tags.
src/server/extensions/commands/builtins/<command>/locales/<lang>.json: These are the output strings for each built in command. Commands that have locale files include help, ip, ai-summary, speedtest, and uuid. You can copy these from the corresponding en.json inside each command locales/ folder. These use short language codes like en or fr.

Adding a new language step by step

1. Copy the English originals

LANG=it-IT
SLANG=it

cp src/locales/en-US.json src/locales/$LANG.json
cp src/public/themes/degoog-theme/locales/en-US.json \
    src/public/themes/degoog-theme/locales/$LANG.json

for cmd in help ip ai-summary speedtest uuid; do
  cp src/server/extensions/commands/builtins/$cmd/locales/en.json \
      src/server/extensions/commands/builtins/$cmd/locales/$SLANG.json
done

2. Translate the values

Open up each copied file and translate every single string value. Make sure you keep all the keys and placeholders like {like_this} exactly as they are. If there is HTML inside the values such as <code> tags, keep it and adapt it to your language wording.

3. Verify

Start your development server with your locale forced so you can check everything. Enable LOG_TRANSLATION to surface any missing keys or locale resolution misses in the console:

DEGOOG_I18N=it-IT LOG_TRANSLATION=true npm run dev

Take a look through the home page, every settings tab, the Configure modal for an engine and a plugin, and trigger each built in command like !help, !ip, or !uuid.

4. Open a pull request

Commit all your new locale files and open a pull request against the develop branch. You should title it feat(i18n): add <Language> translations. Check out the Contributing page for the pull request checklist.

Translations in third party extensions

Plugins, engines, and themes distributed via the Store are responsible for handling their own translations. The pattern works exactly the same way. You just add a locales/ folder inside your extension with one JSON file per language code. The app will pick up these files automatically.

For a plugin named my-plugin, your locale file would be locales/fr.json and the top level key would be plugin-my-plugin. The display name, description, settings field labels, and any output strings for the plugin can all live right under that key. If you want to translate an extension made by someone else, please open a pull request in their specific repository rather than the core project.

Degoog Translations