# How to add translations

Self-hosted LiveSync owns its multilingual catalogue. Commonlib supplies only the typed English messages which its services request; the plug-in combines those keys with its application messages and injects the selected translator at each service composition root.

## Getting ready

1. Clone this repository.

    ```sh
    git clone https://github.com/vrtmrz/obsidian-livesync
    cd obsidian-livesync
    npm ci
    ```

2. Create an `ls-debug` directory below the test Vault's `.obsidian` directory, for example `.obsidian/ls-debug`.

## Add translations for existing messages

1. Edit the human-readable YAML files under `src/common/messagesYAML/`.
2. Regenerate the JSON and TypeScript resources.

    ```sh
    npm run i18n:bake
    ```

3. Build the plug-in in development mode, install it in the test Vault, and run Self-hosted LiveSync.
4. Review any `missing-translation-yyyy-mm-dd.jsonl` file written below `.obsidian/ls-debug`, and add the required translations to the YAML catalogue.
5. Bake and build again, then confirm the displayed text and placeholder substitution in the relevant workflow.

Commit the edited YAML and all regenerated JSON and TypeScript resources together.

## Make a message translatable

1. Add its canonical English entry and translations to `src/common/messagesYAML/`.
2. Replace the source literal with `$msg()` or another existing translation helper, using the English catalogue key as the typed contract.
3. Run `npm run i18n:bake`, build the plug-in, and verify the affected workflow.

When a new message belongs to Commonlib rather than the application, add its canonical English definition and key type in Commonlib first. Add any available translations to LiveSync when consuming that package; untranslated languages use Commonlib's canonical English fallback.