# `jadpo translations`

Keep translations up to date.

The text the server writes for its readers is translated in Jadpo itself (area 10). `missing` lists, by language file, the wording a locale lacks (and what an in-progress locale falls back on), the translations made from default wording that has since changed, and, with `translations: { review: TranslationReview.required }`, the wording waiting for acceptance. `unused` lists the messages no code calls. `update` records, in each translations folder's sources.jadpo_record, which default wording each translation was made from. `accept` records a person's acceptance of a locale's changed wording, and never of a stale translation. `builtin` lists Jadpo's own messages the application can show, with their fields and the wording to translate from. `export` writes every message, its description and its wording for a locale as XLIFF 2.0 or JSON, for Crowdin, Lokalise or any service that reads them, and `import` reads the translations back, checks them as the language files are checked, and writes the language files and the record, or writes nothing.

```text
jadpo translations <action> [locale]
```

## Arguments

- `action`: What to do: missing, unused, update, accept, builtin, export or import
- `locale` (optional): The locale to list, accept or export, such as fr_fr; for import, the file to read

## Flags

- `--format <format>`: For export: xliff (default) or json
- `--out <folder>`: For export: the folder to write to
- `--locale <locale>`: For import: the locale of a JSON file

## On every command

- `--json`: Print data for tools instead of text
- `--help`: Show every flag, with examples
- `--color <when>`: Choose when to use colour

`jadpo translations --json` writes one JSON document to standard output instead of text, with the same exit code. The document has `schemaVersion`, `command` (`"translations"`), `ok`, `data` (what the command produced, `null` when it failed) and `diagnostics` (each error with its `rule`, `reason`, `next` and `help`). A command that needs a terminal refuses `--json` and names the flags that do the same job.

## Examples

```text
# See what is left to translate
jadpo translations missing
# Write every locale's wording for a translation service
jadpo translations export
# Read back what the service translated
jadpo translations import build/translations/fr_fr.xlf
# Record the translations just written
jadpo translations update
# Accept the French wording after reading it
jadpo translations accept fr_fr
# List the messages nothing calls as data for tools
jadpo translations unused --json
# See Jadpo's own messages to word for a new locale
jadpo translations builtin
```

## Errors

- [`cli.translations_arguments`](../errors/cli.translations_arguments.md): Translations command has invalid arguments
- [`translation.exchange_file_invalid`](../errors/translation.exchange_file_invalid.md): Translation exchange file can't be read or written
- [`translation.exchange_unit_unknown`](../errors/translation.exchange_unit_unknown.md): Translation file holds a unit the project does not have
- [`toolchain.artifact_write_failed`](../errors/toolchain.artifact_write_failed.md): Generated file could not be written
- [`toolchain.project_not_found`](../errors/toolchain.project_not_found.md): Project could not be found
- [`toolchain.source_read_failed`](../errors/toolchain.source_read_failed.md): Jadpo source file could not be read