From 0e8eb2cb22d8b722cba7b34f3f2687a8c8e67efc Mon Sep 17 00:00:00 2001 From: silentoplayz Date: Thu, 8 Oct 2026 19:30:59 -0400 Subject: [PATCH] docs: add a page for translating Open WebUI --- docs/contributing.mdx | 9 +------ docs/translating.mdx | 60 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 61 insertions(+), 8 deletions(-) create mode 100644 docs/translating.mdx diff --git a/docs/contributing.mdx b/docs/contributing.mdx index c7831744ae..9580d1fd4c 100644 --- a/docs/contributing.mdx +++ b/docs/contributing.mdx @@ -65,14 +65,7 @@ Help make Open WebUI more accessible by improving docs, writing tutorials, or cr ### Translate the UI -PRs limited to i18n/localization do not require a maintainer request. Open WebUI uses JSON translation files in `src/lib/i18n/locales`. Each subdirectory is named with an [ISO 639 language code](http://www.lingoes.net/en/translator/langcode.htm) (e.g., `en-US`, `fr-FR`). - -To add a new language: - -1. Create a new directory under `src/lib/i18n/locales` named with the appropriate language code -2. Copy the `en-US` translation files into the new directory -3. Translate the string values in each JSON file while preserving the object structure -4. Register the language in `src/lib/i18n/locales/languages.json` +PRs limited to i18n/localization do not require a maintainer request. To fill in missing strings in a language Open WebUI already ships, or to add a new language, see [Translating Open WebUI](/translating). ### Improve accessibility diff --git a/docs/translating.mdx b/docs/translating.mdx new file mode 100644 index 0000000000..cd5f24f2c1 --- /dev/null +++ b/docs/translating.mdx @@ -0,0 +1,60 @@ +--- +sidebar_position: 1650 +title: "Translating Open WebUI" +--- + +# Translating Open WebUI + +If you use Open WebUI in a language other than English, you have probably seen English labels mixed in with your own language. Each one is a string nobody has translated yet, and anyone fluent in the language can fill it in. Translation pull requests are the one kind of code contribution that doesn't need a maintainer to ask for it first. + +Every release adds new strings, and they arrive untranslated in every language, so even a language that is complete today has gaps again after the next release. + +## Find what's missing in your language + +Each language is one file in the [Open WebUI repository](https://github.com/open-webui/open-webui), `src/lib/i18n/locales//translation.json`, where `` is the language's code as listed in `src/lib/i18n/locales/languages.json`, such as `de-DE` or `pt-BR`. Each line pairs a key with its translation, and an empty value is a string nobody has translated: + +```json +"Load content from these URLs?": "", +"Load Model": "Modell laden", +``` + +Open WebUI shows the English text wherever the value is empty. To count the empty values in your language, run this from a checkout of the `dev` branch, with your language's code in place of `de-DE`: + +```bash +grep -c '": ""' src/lib/i18n/locales/de-DE/translation.json +``` + +## Translate the strings + +For most keys, the key is the English text. Keys written as dotted names, such as `settings.personal.general.language.label`, are different. Their English text is the value of the same key in `src/lib/i18n/locales/en-US/translation.json`. Translate that English text, never the name. + +These rules keep a translation working in the interface: + +- **Keep every `{{placeholder}}` exactly as written**, capitalization included, and keep any `\n` line breaks. Open WebUI fills them in when it shows the string. +- **Fill every plural form in your file.** A key such as `{{count}} files_one` comes with `{{count}} files_other`, and languages with more plural forms have more keys: Ukrainian also has `_few` and `_many`. Open WebUI picks the form that matches the number. +- **Leave names untranslated:** Open WebUI, product and provider names, and parameter names such as `top_k`. +- **Use the words your file already uses.** If the file already translates "prompt" one way, a new string that uses a different word reads as a mistake. +- **Change only the values in your language's file.** Don't edit `en-US`, don't rename or reorder keys, and don't run `npm run i18n:parse`, which rewrites the file of every language. + +Before you submit, have a fluent speaker read the whole translation, whether that's you or someone you ask. Machine translation can give you a first draft, but it often gets short labels wrong because it can't see where they appear. "Open" can be a command or a description, and many languages use a different word for each. + +To see the translation in place, run Open WebUI from your checkout as described in [Developing Open WebUI](/getting-started/advanced-topics/development), then choose your language under **Settings > General > Language**. + +## Open the pull request + +- **One language per pull request**, opened against the `dev` branch. +- **Start the title with `i18n:`**, for example `i18n: fill missing German (de-DE) translations`. +- **Follow the [pull request template](https://github.com/open-webui/open-webui/blob/main/.github/pull_request_template.md).** Under **Maintainer Request**, write that the pull request only updates i18n/localization, and tick the checkbox that says so. A pull request without it is closed automatically. +- **Say how the translation was made and who checked it**, for example "machine translated, then reviewed by a native speaker". +- **Complete the Contributor License Agreement** at the end of the template. + +## Add a new language + +1. Create a directory under `src/lib/i18n/locales` named with the language's [ISO 639 code](http://www.lingoes.net/en/translator/langcode.htm), such as `fr-FR`. +2. Copy `src/lib/i18n/locales/en-US/translation.json` into the new directory. +3. Write a translation as the value of every key, following the rules above. +4. Register the language in `src/lib/i18n/locales/languages.json` with its code and title, such as `{ "code": "fr-FR", "title": "French (France)" }`. + +## Where to go next + +Ask translation questions on [Discord](https://discord.gg/5rJgQTnV4s) or in [GitHub Discussions](https://github.com/open-webui/open-webui/discussions). For other ways to help, such as testing the `dev` branch or improving the documentation, see [Contributing](/contributing).