iOS Strings
Strings
The .strings
format is used to surface text in iOS applications. If you’re fetching this format via the API, it will have an HTTP Content-Type
header of text/plain
.
Example:
"welcome.title" = "Welcome, %1$@!";
/* This should only be used on the logout screen */
"logout" = "Logout";
Instructions:
To fetch this via the API, provide the query parameter ?format=ios-strings
.
To fetch this via the CLI, specify format: ios-strings
in the config.yml
file.
Format details:
- Ditto Variables are replaced with interpolation placeholders with a string (@) format specifier; in your client code, you’ll need to ensure that all variables passed as arguments are first converted into strings.
- Notes associated with text items or components will be included as comments above a given key-value pair.
- To use string plural forms, you will need to use the
.stringsdict
format (see below) in conjunction with the.strings
format. - If this format is exported for a specific variant, two comments containing variant metadata will also be included:
/* Variant Name: French */
/* Variant Description: Copy localized for native French speakers */
"welcome.title" = "Welcome, %1$@!";
...
StringsDict
The .stringsdict
format is used to surface plural form text in iOS applications; text without pluralization enabled in Ditto is excluded from output.
For integrating strings that are not pluralized, you should use .stringsdict
in conjunction with iOS .strings
.
If you’re fetching this format via the API, it will have an HTTP Content-Type
header of text/xml
.
Example:
<?xml version="1.0" encoding="utf-8"?>
<plist version="1.0">
<dict>
<!-- Variables: cartCount, username -->
<key>cart.header</key>
<dict>
<key>NSStringLocalizedFormatKey</key>
<string>%1$#@count@</string>
<key>count</key>
<dict>
<key>NSStringFormatSpecTypeKey</key>
<string>NSStringPluralRuleType</string>
<key>NSStringFormatValueTypeKey</key>
<string>d</string>
<key>one</key>
<string>%3$@, you have one item in the cart.</string>
<key>two</key>
<string>%3$@, you have a couple of items in the cart.</string>
<key>other</key>
<string>%3$@, you have %2$@ items in the cart.</string>
</dict>
</dict>
</dict>
</plist>
Instructions:
To fetch this via the API, provide the query parameter ?format=ios-stringsdict
.
To fetch this via the CLI, specify format: ios-stringsdict
in the config.yml
file.
Format details:
The order in which variables are provided as arguments in Swift is relevant to the output. The following code could be used with the example output above:
let localizedString = String.localizedStringWithFormat(
NSLocalizedString(
"cart",
comment: "A description of the user's cart"
),
// The first argument should always be an integer to determine which plural
// form to use
pluralcount,
// Subsequent arguments should be provided in alphabetical order according
// to the names of the Ditto Variables used in a given text item
String(pluralcount),
username,
)
- A comment structured like
<!-- Variables: variable_one, variable_two, ... -->
is included above each key in the.stringsdict
file to indicate the order in which variables should be passed (this will always be alphabetical). - All Ditto Variables are replaced with interpolation placeholders with a string (@) format specifier — in your client code, you’ll need to ensure that all variables passed as arguments are first converted into strings.
- If this format is exported for a specific variant, two comments containing variant metadata will also be included:
<?xml version="1.0" encoding="utf-8"?>
<!-- Variant Name: French -->
<!-- Variant Description: Copy localized for native French speakers -->
<plist version="1.0">
...
</plist>
Integrating .strings
and .stringsdict
files
The Ditto CLI includes special behavior for iOS environments designed to streamline the process of integrating Ditto with iOS projects.
It can automatically package string files into bundles that are ready to import into Xcode, as well as generate Swift code to make string consumption type-safe.
See the iOS section of the CLI Files page to learn more about the CLI’s iOS-specific behavior, or check out the CLI Installation page to get started.