# Tooling for translations

The `jadpo translations` commands list what is missing, keep the record of
what each translation was made from, and exchange wording with translation
services. Each takes `--json` wherever it prints. They succeed whatever
they list, because they answer a question: `jadpo check` is what fails.
`update` and `accept` stop on syntax errors.

## What is missing or unused

`jadpo translations missing [<locale>]` lists, under the language file each
is in:

- the wording a locale lacks and, for a locale in progress, what it falls
  back on;
- the translations made from wording that has since changed;
- with review required, the wording not yet accepted.

`jadpo translations unused` lists the messages, and the enums with
wording, that no code calls. A test doesn't count as a caller. Failures and
emails are used by being reachable and by the email's own sending, so they
are never listed. It also lists your app's wording of library packages'
text that shows nothing
([Packages' text in the exchange](packages-text-in-an-app.md#packages-text-in-the-exchange)).

## Recording and accepting: `update` and `accept`

`jadpo translations update` writes each folder's `sources.jadpo_record`. It
can't tell that a translation was redone, only that it changed. So a
translation with no line, or one reworded since its line, is recorded as
made from today's default wording, and loses its acceptance. One made from
wording that changed, and that wasn't reworded, stays stale with its line
untouched, so the error stays until someone translates it again. `update`
and `accept` say `still stale` for it.

`jadpo translations accept <locale>` does what `update` does for that
locale, then accepts everything of the locale's that isn't stale, so a
person doesn't run both. It takes a supported locale other than the default
and the pseudo-locale. Anything else is `cli.translations_arguments`, which
names the ones it takes.

## Go to definition

In the editor, go to definition goes from a
`translations.<domain>.<message>(...)` call to the message's type first,
then to its member in each language file, in path order. An enum's call
does the same.

## The pseudo-locale

The pseudo-locale, `Locale.en_xa`, writes every message with its letters
accented and the text made longer, for development and tests. It shows up
text that is written into the code instead of translated, and layouts that
are too tight. Its tag is the one Android and Chrome use, in a region
ISO 3166 leaves for private use, so it can't clash with a real locale.
`Locale` has 534 variants: 533 from CLDR and this one.

List it in `supported:` like any locale. Take it out before releasing, or
keep it for a staging build. It needs no language file, is never asked for
wording, and has no translations to list or accept.

It writes the default locale's wording, with that locale's plural rules and
number format, its letters accented (`a` is `á`), about two fifths longer,
in brackets, so a cut-off end shows as a missing `]`. The values a wording
writes aren't accented. A language file `en_xa.jadpo`, if one exists, is
written as it is. Failures' client text is exported in it the same way.

```jadpo
application {}

locales {
    default: Locale.en_gb
    supported: [Locale.en_gb, Locale.en_xa]
}
```

```jadpo
test "the pseudo-locale accents and lengthens the default wording" {
    assert translations.shop.parcels(count: 1, locale: Locale.en_xa) == "[1 þáŕçéļ ~~~~]"
    assert translations.shop.parcels(count: 1234, locale: Locale.en_xa) == "[1,234 þáŕçéļš ~~~~~~]"
}
```

## Jadpo's own messages: `builtin`

`jadpo translations builtin`, with `--json`, lists Jadpo's own messages
your app can show, by feature. Each comes with the fields it may write, the
wording Jadpo ships to translate from, and `needs` and the locale for each
supported locale whose lack of it fails the check, the default included
(none for a locale in progress). It succeeds whatever it lists. Its summary
counts the messages, the ones that need wording (in the problem colour) and
the features. Its one hint is `jadpo check`:

```text
Requests
  invalid_request         needs fr_fr
    The request couldn't be read. Try again.
  invalid_input           needs fr_fr
    Some of the information sent isn't valid. Check it and try again.
  ...

Locales
  text_direction
    left_to_right  ltr
    right_to_left  rtl

11 messages: 10 need wording, 2 features

next: jadpo check  fails until the application words them
```

`jadpo translations missing`, `update` and `accept` take the root folder in
with the rest. Its gaps are listed under `translations/<locale>.jadpo` as
`jadpo.<message>` (never for the default locale, which the error covers),
and an in-progress locale falls back to what Jadpo ships.