.JSON - Phrase Strings

Content is machine translated from English by Phrase Language AI.

File Extensions	.json
API Extension	strings_json
Import	Yes
Export	Yes
Plural forms support	Yes
Description support	Yes
State support	Yes
Metadata support	Yes
Format options	ignore_translation_state export_translation_state export_description export_tags export_system_tags export_max_characters_allowed custom_metadata_columns export_use_ordinal_rules

Phrase Strings JSON format provides a structured way to store and manage translations, incorporating metadata, state tracking, and workflow integration for improved functionality.

This format includes metadata such as localization details, character limits, descriptions, plural form type, and translation states. The state support feature allows better tracking of translation progress and integration with automated workflows.

Field Definitions

Key Object

The key object contains metadata and settings for each translation key.

Field	Required	Type	Description
`name`	Yes	String	Unique identifier for the key.
`description`	No	String	A brief explanation of the key’s purpose.
`plural`	No	Boolean	Specifies if the key supports pluralization.
`use_ordinal_rules`	No	Boolean	Indicates whether key plural forms are ordinal. Defaults to `false` if omitted. Used during import and export.
`max_characters_allowed`	No	Integer/Null	Maximum number of characters allowed. `null` means no limit.
`tags`	No	Array	Categorization tags for filtering and organization.
`metadata`	No	Object	Stores additional metadata as key-value pairs. It can be added or updated but not removed. To remove metadata, set its value to an empty string.

Translations Object

The translations object contains localized translations for a given key.

Field	Required	Type	Description
`locale`	Yes	String	The name or identifier of the locale.
`locale_code`	No	String	The locale’s language code (e.g., en-US, fr-FR).
`content`	Yes	String/Object	The translated content. If pluralized, an object mapping plural forms based on the key’s `use_ordinal_rules` setting.
`state`	No	String	The state of the translation. Supported translation states: untranslated unverified translated reviewed

Format Options

Identifier	ignore_translation_state
Type	boolean
Upload	Yes
Download	No
Default	false
Description	If true, ignores state values in imported translations, meaning that the uploaded file will not overwrite existing translation states.

Identifier	export_translation_state
Type	boolean
Upload	No
Download	Yes
Default	true
Description	Includes state values in exported translations; if set to false, state information will be omitted from the exported file.

Identifier	export_system_tags
Type	boolean
Upload	No
Download	Yes
Default	false
Description	If true, exports system tags along with keys and translations.

Identifier	export_tags
Type	boolean
Upload	No
Download	Yes
Default	false
Description	If true, exports tags along with keys and translations.

Identifier	export_description
Type	boolean
Upload	No
Download	Yes
Default	true
Description	Exports key description.

Identifier	export_max_characters_allowed
Type	boolean
Upload	No
Download	Yes
Default	true
Description	Exports the key character limit along with keys and translations.

Identifier	custom_metadata_columns
Type	hash
Upload	No
Download	Yes
Default	[empty]
Description	HashMap of custom metadata values that need to be imported or exported: Key = Name of the custom metadata property, as defined in Phrase Strings. Value = Column index (1, 2, 3, etc.) where the property is in the imported file/where the property should be in the exported file.

Identifier	export_use_ordinal_rules
Type	boolean
Upload	No
Download	Yes
Default	false
Description	If true, the `use_ordinal_rules` field is displayed in the downloaded file. If downloading files via the UI, use the corresponding option Add plural type for each key.

Code Sample

{
  "welcome_message": {
    "key": {
      "description": "Message displayed on the welcome screen",
      "plural": false,
      "max_characters_allowed": 100,
      "tags": ["UI", "greeting"],
      "metadata": {
        "created_by": "admin",
        "created_at": "2024-06-20T12:34:56Z"
      }
    },
    "translations": [
      {
        "locale": "English (United States)",
        "locale_code": "en-US",
        "content": "Welcome to our application!",
        "state": "reviewed"
      },
      {
        "locale": "French (France)",
        "locale_code": "fr-FR",
        "content": "Bienvenue dans notre application !",
        "state": "translated"
      }
    ]
  }
}

Plural forms

This format uses named categories to identify the different pluralizations of a key. The following categories are reserved for plural forms:

.zero | .one | .two | .few | .many | .other

Example names for correctly identified, persisted and marked pluralized keys:

inbox.messages.notification.one
inbox.messages.notification.other

Plural form usage is configured through the use_ordinal_rules field. If use_ordinal_rules is false or unset, cardinal pluralization rules will apply.

Example Input

{
  "rank": {
    "use_ordinal_rules": true,
    "values": {
      "one": "1st place",
      "two": "2nd place",
      "few": "3rd place",
      "other": "%dth place"
    }
  }