Help me build i18n localization

[Aladincz]

Self Checks

• I have searched for existing issues search for existing issues, including closed ones.
• I confirm that I am using English to submit this report (我已阅读并同意 Language Policy).
• [FOR CHINESE USERS] 请务必使用英文提交 Issue，否则会被关闭。谢谢！:)
• Please do not modify this template :) and fill in all the required fields.

1. Is this request related to a challenge you're experiencing? Tell me about your story.

After searching for any mention of localization and I finally found internationalization :D. Times are changing.

I read the guide and found that I do not understand most of steps. I can translate jsons but I have no clue how to bild proper PR for this and where are all those other files mentioned.

If there would be kind person who would guide/help me, I will be glad. I would prefer that to AI. I want to make Czech, cs-CZ i guess, locale.

Thanks

2. Additional context or comments

No response

[dosubot[bot]]

Happy to walk you through it — adding a locale is more mechanical than it looks. Since Czech (cs-CZ) isn't supported yet, the work splits into registering the locale and supplying the translated JSON.

1. Register the locale (web/i18n-config/)

• languages.ts — add an entry to the languages array with value: 'cs-CZ', a name, prompt_name, an example greeting, and supported: true. This file drives the UI language picker [1].

• language.ts — add 'cs-CZ': 'cs' to localeMap [2].

• locale-resources/cs-CZ.ts — a small loader file. Polish's looks like this:

  export const loadResource = (fileNamespace: string) =>
    import(`../../i18n/pl-PL/${fileNamespace}.json`)

  Copy the pattern and point it at ../../i18n/cs-CZ/${fileNamespace}.json [3]. load-resource.ts calls this to lazily import each namespace at runtime [4].

2. Add the translations (web/i18n/cs-CZ/)

Create the directory with the same 37 JSON files found under web/i18n/en-US/ (app.json, common.json, workflow.json, dataset.json, etc.), one per feature area [5]. Key structure and placeholders ({{variable}}, ${variable}, HTML tags) must match en-US exactly, since i18next is configured with keySeparator: false, so dots are literal characters in keys rather than nesting [6]. You don't need resources.ts changes — it maps shared namespace names uniformly across locales [7].

3. Backend (optional)

api/constants/languages.py holds a language_timezone_mapping dict pairing each locale with a default timezone (e.g. "pl-PL": "Europe/Warsaw"). Add "cs-CZ": "Europe/Prague" if you want the backend to accept it as a valid interface_language [8].

4. Validate before opening the PR

From web/:

pnpm run i18n:check                                    # all locales/files
pnpm run i18n:check --file app billing --lang cs-CZ    # scoped check

This compares each locale's keys against en-US and reports missing/extra keys, and CI runs the same thing, so a clean local pass saves review round-trips [9].

A useful precedent: when Slovenian (sl-SI) was added, the work was split — base locale directory and config wiring first, then a follow-up PR adding the slSI language label to every other locale's common.json "language" list so it displays correctly for users on other UI languages [10]. Do the same for Czech: add a csCZ label with "Čeština" to the common.json language map in en-US and ideally a few other locales.

For the PR itself: fork, branch, add the files, run pnpm run i18n:check, and open it against langgenius/dify referencing an issue — the contribution guide asks for an associated issue linked as Fixes #<issue number> [11].

You don't have to translate all 37 files before your first PR; partial sets are common and the check will flag remaining gaps against en-US. Want me to pull up a specific en-US JSON file, or the common.json "language" map format so you can see exactly where Czech slots in?

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.

[leogrox]

Happy to walk you through it. The guide is accurate, but it leaves out a few things that will cost you an afternoon.

The reference PR has stale paths. #42291 (Azerbaijani) is the right shape to copy, but it landed just before #42482 moved everything: web/i18n-config/ is gone and the files now live under web/i18n/. Use the paths below, not the ones in that diff.

For cs-CZ, besides the translations:

1. web/i18n/languages.ts: add the entry next to the others:

   {
     value: 'cs-CZ',
     name: 'Čeština (Česko)',
     prompt_name: 'Czech',
     example: 'Ahoj, Dify!',
     supported: true,
   },

2. web/i18n/locales/cs-CZ/: the 37 JSON namespaces, copied from locales/en-US/ and translated. Same flat keys, same placeholders. keySeparator is off, so a dot is part of the key, not a nesting level.
3. web/i18n/locale-resources/cs-CZ.ts:

   export const loadResource = (fileNamespace: string) =>
     import(`../locales/cs-CZ/${fileNamespace}.json`)

4. web/i18n/language.ts: add 'cs-CZ': 'cs' to localeMap. Leave DOC_LANGUAGE and ACCESS_CONTROL_TEMPLATE_LANGUAGE alone; they only list languages with translated docs and fall back to English.
5. web/service/use-plugins.ts (once) and web/service/use-triggers.ts (twice): add 'cs-CZ': en next to 'az-AZ': en. Those objects are typed Record<Locale | PluginLanguage, string> and Locale is derived from languages.ts, so the type check fails as soon as step 1 is in and these aren't.
6. api/constants/languages.py: add the timezone, "cs-CZ": "Europe/Prague".

The one nobody mentions: dayjs locales are imported statically, in two places: web/hooks/use-format-time-from-now.ts and web/utils/format.ts. Add import 'dayjs/locale/cs' to both. Without it, relative and formatted dates silently stay in English, and nothing errors.

Then, from web/:

pnpm i18n:check

It compares your files against en-US and reports missing and extra keys. It only looks at locales with supported: true, so if you leave that flag off it skips yours entirely.

For the PR: fork, branch, and title it feat(i18n): add Czech (cs-CZ) translation, matching #42291. You don't need all 37 files in one go; #42291 was followed by #42495 filling in what was missing.

[Aladincz]

Hi guys. I throw it on agent. Seems made good job. Checked few jsons and found just few minor glitches. Have to go through those long one yet but you can check whether other files match requirements. Thanks
dify-cs-cz.zip

And how is it with documentation for Dify?

[Aladincz]

@LGUIUX Sorry, I had to post new version. I have found that agent mixed all workflow jsons into one and at leas one another group too. I had to fix it so zip is just preview.

[leogrox]

Docs live in a separate repo, langgenius/dify-docs, with their own contribution flow; the web UI translation doesn't depend on it.

On the zip: I'd skip it and open the PR straight from a fork instead. Run pnpm i18n:check from web/ first; it catches exactly what your agent broke (keys landing in the wrong namespace show up as missing in one file and extra in another). It only checks locales with supported: true, so set that before you run it. A partial PR is fine, #42291 went in that way.

[Icaro0310]

In the Dify codebase the web frontend uses i18next, so adding a locale is mostly file work. Under web/i18n/ every language lives in its own folder (en-US, pt-BR, zh-Hans ...) split into per-module .ts files like common.ts, layout.ts, custom.ts. To add one, copy web/i18n/en-US to your locale's folder and translate the values.

Then register it in web/i18n/i18next-config.ts (there's a supportedLngs list) so the language picker and routing pick it up. There's also an auto-gen script in web/i18n/ (check the scripts in web/package.json) that fills any missing keys with the English fallback, useful for catching what you forgot.

Partial translations are fine for a PR, missing keys fall back to English. Test it by switching language in the profile menu and clicking around the console.

—
Check out my Repositories: github.com/Icaro0310 · Website: icaro0310.github.io