# Strings parser ## Input The strings parser accepts a `strings` file, typically `Localizable.strings`. It will parse each string in this file, including the type information for formatting parameters. The strings file will be converted into a structured tree version, where each string is separated into components by the `.` character (note: you can choose another separator if you need, using the `separator` option, see [Customization](#customization) below). We call this the `dot syntax`, each component representing a level. For example, the following strings: ``` "some.deep.structure" "some.deep.something" "hello.world" ``` will be parsed into the following structure (not showing the rest of the structure, such as values and types): ```swift [ "some": [ "deep": [ "structure", "something" ] ], "hello": [ "world" ] ] ``` ### Filter The default filter for this command is: `[^/]\.(?i:strings|stringsdict)$`. That means it'll accept any file with the extension `strings` or `stringsdict`. You can provide a custom filter using the `filter` option, it accepts any valid regular expression. See the [Config file documentation](../ConfigFile.md) for more information. ## Customization | Option Name | Default Value | Description | | -------------- | ------------- | ----------- | | `separator` | `.` | Each key is separated into components using the given separator, to form a structure as described in the [explanation above](#input). | ## Templates * [See here](../templates/strings) for a list of templates bundled with SwiftGen and their documentation. * If you want to write custom templates, make sure to check the [stencil context documentation](../SwiftGenKit%20Contexts/strings.md) to see what data is available after parsing. ## Plurals SwiftGen supports definitions of plurals in `.stringsdict` files. (Note: only non-nested plural variables are supported for now) ### Supported

Basic Example

This example should cover the most common use case of plurals that is also supported by most of the translation management services. ```xml competition.event.number-of-matches NSStringLocalizedFormatKey %#@Matches@ Matches NSStringFormatSpecTypeKey NSStringPluralRuleType NSStringFormatValueTypeKey ld zero No matches one %ld match other %ld matches ```

Mixed placeholders and variables in format key

```xml mixed.placeholders-and-variables.string-int NSStringLocalizedFormatKey %@ %#@has_rating@ has_rating NSStringFormatSpecTypeKey NSStringPluralRuleType NSStringFormatValueTypeKey d zero has no rating one has one rating other has %d ratings ```

Variables with positional arguments in format key

```xml multiple.placeholders-and-variables.int-string-string NSStringLocalizedFormatKey Your %3$@ list contains %1$#@first@ %2$@. first NSStringFormatSpecTypeKey NSStringPluralRuleType NSStringFormatValueTypeKey d zero no items. Add one one one item. You should buy it other %1$d items. You should buy them ```

Multiple variables in format key

```xml multiple.variables.three-variables-in-formatkey NSStringLocalizedFormatKey %#@files@ (%#@bytes@, %#@minutes@) files NSStringFormatSpecTypeKey NSStringPluralRuleType NSStringFormatValueTypeKey d one %d file remaining other %d files remaining bytes NSStringFormatSpecTypeKey NSStringPluralRuleType NSStringFormatValueTypeKey d one %d byte other %d bytes minutes NSStringFormatSpecTypeKey NSStringPluralRuleType NSStringFormatValueTypeKey d one %d minute other %d minutes ```

### Not supported

Nested format keys in variables

Note: in practice this should hopefully be very rare. Especially, if you're using tools like Lokalize, PhraseApp, POEditor, or similar to export your `stringsdict`, it's unlikely that they'll ever generate that kind of convoluted structure for your `stringsdict`. ```xml nested.formatkey-in-variable NSStringLocalizedFormatKey %#@geese@ geese NSStringFormatSpecTypeKey NSStringPluralRuleType NSStringFormatValueTypeKey d one A goose landed on %#@goose_fields@ other %d geese landed on %#@geese_fields@ goose_fields NSStringFormatSpecTypeKey NSStringPluralRuleType NSStringFormatValueTypeKey d one its own field other its own %d fields geese_fields NSStringFormatSpecTypeKey NSStringPluralRuleType NSStringFormatValueTypeKey d one their shared field other their %d fields ```

Placeholders that are only used in the variables but not in the format key

This plural entry would work with plain `NSLocalizedString`, as Foundation will pass the whole list of arguments to each substituted format specifier – e.g. in this case passing a `String` and an `Int` would work with `NSLocalizedString`. But SwiftGen only parses the `NSStringLocalizedFormatKey` in a `stringsdict` to find possible placeholders, because parsing all possible plural rules for placeholders as well could result in different amounts of placeholders for different amounts or different languages. ```xml unsupported-use.placeholders-in-variable-rule.string-int NSStringLocalizedFormatKey %#@elements@ elements NSStringFormatSpecTypeKey NSStringPluralRuleType NSStringFormatValueTypeKey d zero %@ has no rating one %@ has one rating other %@ has %d ratings ```