Translation request¶

Schema¶

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¶

"some_key_from_transl"

This resolves to a singular KeyedTranslationRequest with no arguments.

Extended format¶

{
  "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.

{
  "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:

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.
```
{
  "my_push": {
    "other": "You have %d unread messages"
  }
}
```

Request the string from the push message:

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

The request resolves to You have 12 unread messages.