# Translation request

## Schema

[https://schemas.acrobits.net/core/requests/translation.json](https://schemas.acrobits.net/core/requests/translation.json)

## About

External systems can request a translated string from the app through a common format called a **Translation request**.


## Request types

A request can be either a `RawTranslationRequest` or a `KeyedTranslationRequest`.

### `RawTranslationRequest`

Describes a raw, non-translatable string that supports argument substitution.

It contains these fields:

- `raw`: **required.** Raw string that can contain arguments.
- `args`: **optional.** Array of arguments. Supported types are integer, float, string, and Boolean.

Use a raw request when localization is not required. Because the string is not associated with a locale, the app performs only argument substitution and transformation.

### `KeyedTranslationRequest`

References an existing translatable string in the app. It supports plurals and argument substitution.

It contains these fields:

- `key`: **required.** ID from the translation system.
- `count`: **optional.** Value used to resolve plurals. If omitted, the key resolves as singular.
- `args`: **optional.** Array of arguments. Supported types are integer, float, string, and Boolean.

## JSON representation

Translation requests provide a unified JSON format. They support compact and extended representations, both of which resolve unambiguously to a keyed or raw request.

### Compact format

```json
"some_key_from_transl"
```

This resolves to a singular `KeyedTranslationRequest` with no arguments.

### Extended format

```json
{
  "key": "some_key_from_transl",
  "count": 25,
  "args": [
    "Yay!",
    12,
    3.1415,
    false
  ]
}
```

This resolves to a `KeyedTranslationRequest` with arguments and a plural count of `25`. The `args` and `count` fields are optional and can be omitted.

!!! warning

    Omitting `count` changes the semantics: the key resolves as singular. Setting `count` to `1` resolves it as plural with a count of one.

```json
{
  "raw": "I %s can %d support %f arguments %b",
  "args": [
    "Yay!",
    25,
    3.1415,
    false
  ]
}
```

This resolves to a `RawTranslationRequest` with arguments. The resulting string undergoes argument substitution and is displayed without using a translation key.

## Argument transformations

Both keyed and raw requests support argument substitution. Some systems can also transform arguments, for example by performing contact matching.


## Requesting a localized string from an external system

For example, to display a localized message for an incoming push notification:

1. Add a translation fragment containing the localized string. Do not rely on strings embedded in the app because their IDs are not stable. The translation system supports an unlimited number of
   fragments.

    ```json
    {
      "my_push": {
        "other": "You have %d unread messages"
      }
    }
    ```

2. Request the string from the push message:

    ```json
    {
      "key": "my_push",
      "count": 12,
      "args": [12]
    }
    ```

The request resolves to `You have 12 unread messages`.