logseq/docs/contributing-to-translations.md

Intro

Thanks for helping improve Logseq translations.

This guide is for contributors who translate existing UI text or add missing translations for a locale. It is not the guide for changing application code, inventing dictionary keys, or rewriting the English source text in src/resources/dicts/en.edn.

If the English wording or key name is wrong, ask a developer to update en.edn and follow the key naming guide.

Setup

To run the commands in this doc, install Babashka.

Where Translations Live

Translation dictionaries live under src/resources/dicts/. Each locale has its own EDN file, for example es.edn.

en.edn is the source of truth for keys and English text. Most translation contributors only need to edit their locale file.

Find Missing Translations

To see the overall translation status of every locale:

bb lang:list

That table includes :untranslated-count, which shows how many English keys are still missing for each locale, and :same-as-en-count, which helps you spot locales that still contain entries copied from English.

To see which entries are missing for one locale, use es as an example:

bb lang:missing es

To print copy/paste-ready entries:

bb lang:missing es --copy

That command prints the missing keys and the current English value so you can paste them into your locale file and translate them there.

Find Entries Still Matching English

To list them for one locale, use es as an example:

bb lang:pseudo es

This is a review tool, not a hard error. Some entries may legitimately match English, but many are unfinished translations copied from en.edn.

Edit a Locale

1. Run bb lang:missing <locale>.
2. Add the missing keys to src/resources/dicts/<locale>.edn.
3. Save the file.
4. Run bb lang:missing <locale> again until the list is empty or contains only entries you want to leave for later.

Missing keys are allowed. Logseq falls back to English automatically, so do not copy English into your locale file just to make the list shorter.

Editing Tips

• Translate the complete sentence or label owned by the key. Do not rename keys or split one sentence across multiple keys.
• If the English value is a plain string, keep your locale value a plain string.
• Keep placeholders exactly aligned with English, for example {1} and {2}.
• If the English value uses hiccup or (fn ...), keep the same outer shape and translate only the user-visible strings inside it. If changing that structure seems necessary, ask a developer for help.
• Preserve emoji and icon glyphs from en.edn exactly, but use punctuation that is natural for your language.
• If a sentence is already correct in your language without plural logic, use a plain string. Do not add function logic just because English does.

Fix Mistakes

Run this before submitting translation changes:

bb lang:validate-translations

It checks for:

• translation keys referenced from code that do not exist in en.edn
• locale keys that do not exist in en.edn
• dictionary keys that are no longer used
• placeholder mismatches such as {1} vs {2}
• locale entries that no longer match an English rich-translation shape

bb lang:validate-translations does not flag entries that still match English. Use bb lang:pseudo <locale> when you want to review those separately.

To remove stale or invalid keys automatically:

bb lang:validate-translations --fix

--fix removes invalid or unused keys. It does not repair placeholder mistakes or rewrite rich translations for you.

After editing dictionary files, run:

bb lang:format-dicts

This restores the repo's canonical key ordering and namespace spacing.

You do not need bb lang:lint-hardcoded for translation-only work. That command is for developers who are editing UI code.

Add a Language

To add a new language:

1. Add an entry to frontend.dicts/languages.
2. Create a new file under src/resources/dicts/ and name it after the locale, for example zz.edn.
3. Add that file to frontend.dicts/dicts.
4. Use the bb lang:missing <locale> workflow to populate translations.
5. Run bb lang:validate-translations and bb lang:format-dicts.