Anatomy of a Document

Stringer locale documents are in YAML format. Below is an example of a locale document:

---
title: "Stringer"
parts:
- translation:
    key: "toolbar.new.tooltip"
    title: "Tooltip for new string toolbar button"
    value: "Creates a new and blank locale file"
    variants: {}
- translation:
    key: "toolbar.open.tooltip"
    title: "Tooltip for open file toolbar button"
    value: "Open a locale file"
    variants: {}
sourceLanguage: "en"
targetLanguages:
- "fr"

At a high level a locale includes:

• title - translation set title (usually name of application)
• parts - array of translation strings
  • tanslation - definition of a translation
• sourceLanguage - language that the locale is authored in
• targetLanguage - languages that the locale should be translated to

The locale components are expanded on below:

Title

This is a title for the locale, this should describe the application that the locale is for.

In the locale yaml, this value should be set in the title attribute at the root level. In the stringer ui, the title is editable on the left panel of the document window.

Source Language

Each translation in the locale file has a value, and the source language is the ISO code for the language that each translation value is written in. For example, if the value of each string is written in english, then this attribute will be en.

In the locale yaml, the source language is set in the sourceLanguage attribute. In the stringer ui, the source language is set in the source language combo box in the left panel.

Target Languages

The locale file is capable of storing translated strings in multiple languages. These are languages other than the source language where we will keep strings.

For example, if we want to have Afrikaans variants of each string, then one would add af to the list of target languages.

In the locale yaml, the target languages are an array set on the targetLanguages attribute. In the stringer ui, the target languages are set on the target language list on the left panel.

Packages

Packages refers to a list of code packages that the locale file is responsible for. This allows large projects to be broken up over a number of locale files.

An example of a package entry for stringer could be com.biggerconcept.stringer.

These are stored in the locale yaml as an array on the packages attribute. In the stringer ui, these can be set at the bottom of the left panel.

Parts and Translations

Parts is an array of translation string definitions.

They are managed automatically by the appplication. Each part can have multiple translations.

Translation entries are the registration of each string. A translation can support the following attributes:

• key - unique identifier of the string.
• title - description of the string.
• value - value of the string in the source language
• variants - map of the string translated into different languages.
• screenshot - URL of a screenshot of the string in context.
• hidden - boolean value to indicate whether the string is visible to users or not.
• wip - boolean value to mark strings as work in progress.

Strings are navicable through the tree in the middle panel. The translation attributes are editable in the right panel.

Key

Each translation requires a unique key to identify and use it. In Stringer YAML, the key is a dot separated string.

An example of this could be a toolbar new button tooltip which would be expressed like this:

toolbar.new.tooltip

The stringer UI will render this string under toolbar and new parent items in the tree view.

Title

The title of the string should describe what the string is for. Returning to the new button tooltip example from above, you might choose to describe this string as:

A tooltip text for the new document toolbar button

This string can be used to give a native language speaking translator context about what the string is actually for. This coupled with the screenshot attribute (see below), can be used to ensure that the translations are as accurate as possible.

Value

The value is the string in the source language. Again returning to the new tooltip example from above, if the source language is english then the value of the tooltip would be something like:

Create new document

Variants

The variants are a map of the translated versions of the string. The key of the map is the ISO code for the language (for example Afrikaans would be af, French would be fr and so on.)

This attribute allows the document to hold variations of the string in different languages.

Screenshot

The screenshot can help give additional context of the string beyond the title by showing the string in context.

This should be a publically accessible screenshot of the string in context.

Hidden

Hidden is a true/false value that marks the string as visible or invisible to users. This is additional metadata that you might use in an app consuming a Stringer YAML file.

WIP

WIP is a true/false value that marks the string as work in progress when true. Similar to the hidden attribute, one might want to use this annotation when consuming a Stringer YAML file in another application.