# `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
- `--full`: Show everything a report shortens
- `--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`](/docs/errors/cli.translations_arguments.md): A `jadpo translations` command names no action, one it doesn't have, or a locale the project doesn't translate into
- [`translation.exchange_file_invalid`](/docs/errors/translation.exchange_file_invalid.md): A file given to `jadpo translations import` isn't XLIFF 2.x or JSON in the shape `export` writes, or can't be read as one
- [`translation.exchange_unit_unknown`](/docs/errors/translation.exchange_unit_unknown.md): A file given to `jadpo translations import` holds a unit of wording the project doesn't have
- [`toolchain.artifact_write_failed`](/docs/errors/toolchain.artifact_write_failed.md): A file Jadpo writes for you, such as a record, couldn't be written, usually because it or its folder is read-only
- [`toolchain.project_not_found`](/docs/errors/toolchain.project_not_found.md): You ran a command that works on a project in a folder with no `app.jadpo`, in it or in any folder above it
- [`toolchain.source_read_failed`](/docs/errors/toolchain.source_read_failed.md): A `.jadpo` file in the project couldn't be read, because it isn't UTF-8 text or you aren't allowed to read it