Translating Locales

Translating / improving a locale in Trilium

Trilium's UI is localized with i18next. English is the source of truth; other locales are normally crowd-translated via Hosted Weblate. This skill is for the maintainer case: deliberately filling a locale that lags behind (the recurring one is Romanian, ro).

Scope — this skill fills an already-registered locale. To add a brand-new locale (e.g. Polish) you must first do the one-time registration and build wiring; that's a separate task. Follow docs/Developer Guide/Developer Guide/Concepts/Internationalisation Translations/Adding a new locale.md to register it, then come back here to translate the strings.

en-GB is the exception and must never be filled. The en catalogues are US English, and en-GB carries only the strings whose British spelling differs — "color_type": "Colour", "centerContent": "Keep content centred" — falling back to en for the rest. So measure en-GB reporting a few percent is the intended state, not a gap: an entry that merely repeats the English is noise, and measure would then report it as untranslated anyway. Use merge en-GB <catalog> <file> for the handful of spelling variants a change introduces, and nothing else.

Every mechanical step is locale.mjs — measure, export, validate, merge, audit. Read romanian.md for Romanian grammar and terminology.

S=.claude/skills/translating-locales/locale.mjs
node $S measure                                   # coverage of every locale, both catalogs
node $S measure ro -v                             # one locale, listing missing + untranslated keys
node $S export ro client --chunk 150              # work list (English source) → a temp dir
node $S validate ro client <files…>               # placeholders / whitespace / plural categories
node $S merge ro client <files…>                  # apply, preserving key order + formatting
node $S audit-plurals ro client                   # groups missing a category the locale requires

export writes { key: englishValue }; translate into a flat { key: translatedValue } file and feed it to validate then merge. Chunking matters: a locale that is 1000+ strings behind does not fit one drafting pass, and validate/merge both take a list of files.

How Weblate sync works here (merging a PR IS picked up — no separate upload needed)

Weblate is linked to this repo with the GitHub pull-request push method: .github/workflows/i18n.yml triggers on push to weblate:* branches, and Weblate opens PRs into the repo (the recurring Translations update from Hosted Weblate (#…) PRs). The locale translation.json / server.json files are tracked Weblate components. Consequently:

• Merging a PR that edits a locale file IS picked up by Weblate. On its next pull of the default branch, Weblate imports the new/changed translations into its database — they persist and show up for other contributors. They are not discarded or overwritten. With the PR-based push method Weblate never force-pushes the default branch, so the repo is authoritative and Weblate merges from it.
• A direct-to-repo PR is therefore a fully valid, durable way to land translations. You do NOT need to separately upload the file into Weblate.
• This is the opposite of arbitrary repo files (README, docs): those aren't part of any Weblate component, so Weblate simply ignores them.
• Real (narrow) caveat: a true conflict only arises if the same key is edited simultaneously in Weblate (pending, un-pushed) and in the repo — then Weblate's merge/rebase conflict handling picks the winner. Filling previously-empty/untranslated strings doesn't conflict.
• CLAUDE.md's "only add new keys to en/translation.json" rule is about where new source strings originate (so they enter the translation pipeline), not a prohibition on landing translations for an existing locale via the repo.
• Changing an English source string (e.g. pluralizing a key) makes Weblate flag the matching translations in other locales as needing review and drop orphaned removed-key entries — normal, and it doesn't affect the locale you just filled.

File locations

All three have their own EN↔locale pair — do all three; measure reports them side by side. entry is easy to forget: it is a separate i18next namespace loaded on its own by the three pre-login pages, so a locale can read 100% on client while its login screen is entirely English. Several of its keys (login.*, the SSO errors) are near-duplicates of server.json ones — translate them the same way.

server.json is misnamed: it is the catalog for every runtime outside the browser UI — apps/server, the Electron main process, packages/trilium-core, and the standalone worker, which loads it with ns: "server" from the copy of apps/server/src/assets that its vite build emits under server-assets. Translating it therefore covers the standalone and mobile builds too, and a missing key there is not "server-only" breakage.

Workflow

1. Measure the gap

node $S measure <locale> -v. Two numbers matter: missing (absent from the locale) and untranslated (present but byte-identical to English). The latter is mostly legitimate proper nouns — -v lists them so you can tell.

2. Export the work list

node $S export <locale> <catalog> --chunk 150. Chunks of ~150 strings keep each drafting pass reviewable; --out DIR if you want them somewhere specific (default: a fresh temp dir).

3. Draft the translations

• Probe the existing file first and match its terminology and tone. RO uses notiță for "note", Anulează for "Cancel", formal-plural address (Selectați). Don't invent a second term for something the file already names.
• Keep proper nouns and kept technical terms in English: ETAPI, MCP, OAuth/OpenID, Markdown, Widget, Mermaid, Bing/Google/Gantt/Kanban/…, and words spelled the same in the target language. Also keep literal UI labels of other products quoted in English (Notion's "Create folders for subpages") — the user has to find that exact control.
• Preserve every placeholder exactly (the #1 source of bugs) — validate checks all of these:
  • {{var}}, {{- var}} (unescaped — keep the hyphen), {keyword} (single-brace, e.g. date patterns and search-engine URLs)
  • JSX/<Trans> tags: <buildRevision />, <Note/>, <code>…</code>; HTML entities like →
  • \n line breaks, leading/trailing spaces, trailing punctuation
• Honor i18next plural suffixes — the locale's required categories, not English's two. See below.
• Copy each form's placeholders from its own English key, not from the group. English often writes _one without {{count}} ("An archived note was copied here", "1 hidden note") while _other has it. validate compares a locale-only _few against _other, so put {{count}} in _few/_other and leave _one as English left it.