Dasemu
40631362b3
Establishes version control for the personal Logseq DB fork before starting the server-client architecture migration and domain features described in docs/agent-guide and the approved implementation plan. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
140 lines
4.3 KiB
Markdown
140 lines
4.3 KiB
Markdown
## 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](i18n-key-naming.md).
|
|
|
|
## Setup
|
|
|
|
To run the commands in this doc, install
|
|
[Babashka](https://github.com/babashka/babashka#installation).
|
|
|
|
## Where Translations Live
|
|
|
|
Translation dictionaries live under
|
|
[src/resources/dicts/](https://github.com/logseq/logseq/blob/master/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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
bb lang:missing es
|
|
```
|
|
|
|
To print copy/paste-ready entries:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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`.
|