Twine File Format

Along with what is outlined in the original format, there are a few more formatting features we've added.

Plural Formatting

To distinguish plural resources from regular resources, the twine file is separated into two types of sections:

• Uncategorized
• Plural categories

Uncategorized encompasses all strings that are not pluralized.

Plural categories are the rest of the categories, where each section is one plural set.

To illustrate this:

[[n_years]]
  [n_years__one]
    en = %d year
    ios = %#@n_years@
  [n_years__other]
    en = %d years
    ios = %#@n_years@

[[Uncategorized]]
  [hello_world]
    en = Hello World!
  [n_years]
    en = %#@n_years@

n_years is the section name and the key of the plural.

The __ Notation

n_years__one uses the double underscores (__) to separate the plural value key out. Twine will look for __ to find the plural value key to format the plurals properly. So the plural will look like this in Android and iOS format:

<plurals name="n_years">
  <item quantity="one">%d year</item>
  <item quantity="other">%d years</item>
</plurals>

<key>n_years</key>
  <dict>
  <key>NSStringLocalizedFormatKey</key>
  <string>%#@n_years@</string>
  <key>n_years</key>
  <dict>
    <key>NSStringFormatSpecTypeKey</key>
    <string>NSStringPluralRuleType</string>
    <key>NSStringFormatValueTypeKey</key>
    <string>d</string>
    <key>one</key>
    <string>%d year</string>
    <key>other</key>
    <string>%d years</string>
  </dict>
</dict>

The ios Field

Looking closer at our example, another feature to take note of is the ios field:

[[n_years]]
  [n_years__one]
    en = %d year
    ios = %#@n_years@
  [n_years__other]
    en = %d years
    ios = %#@n_years@

[[Uncategorized]]
  [hello_world]
    en = Hello World!
  [n_years]
    en = %#@n_years@

iOS plural resources have another key for their plural resources called the NSStringLocalizedFormatKey. This has a snake cased string surrounded by %#@key_here@ and this key must be included in the main Localizable.strings file with the same key of the entire plural as its key. (ie. n_years = %#@n_years@;) This is why ios = %#@key_here@ was introduced and you'll notice it'll also be a definition under Uncategorized because of iOS resource specifications.

HTML-Styling

Android supports two ways of adding HTML-styling to string resources.

<string name="clickable_string"><a href="/clickable">clickable string</a></string>
<string name="be_bold"><![CDATA[be <b>bold</b>]]></string>

To have these appear with HTML-styling after passing through Twine, we defined the convention where definition values surrounded by `` are written verbatim. Otherwise, special characters like < will be escaped to `<` and Android will not read resources that use these notations with escaped characters. As a result, the Twine file will look something like this:

[[Uncategorized]]
  [clickable_string]
    en = ``<a href="/clickable">clickable string</a>``
  [be_bold]
    en = ``<![CDATA[be <b>bold</b>]]></a>``

These strings will be ignored when generating iOS string resources because iOS does not support HTML-styling in this convention with such functionality available from their string resource files.