# 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
```