Markup Formatting Reference: Localization Key

Add a LocalizationKey callout to allow Quick Help content in playgrounds to adapt to different languages.

Works with:

✓ Playgrounds
Symbol documentation

Syntax

* | + | - LocalizationKey: symbol-localization-key

A LocalizationKey callout provides a unique identifier that maps to a corresponding key-value pair in the localized string resource. At runtime, the Quick Help content for the symbol is replaced by the value for this key in the localized string resource. If the localized string resource for a language doesn’t provide a corresponding key-value pair, the unlocalized content is used.

Requirements

To enable Quick Help localization in a playground, provide a QuickHelp.strings file for each supported locale in the PrivateResources directory of the containing page, chapter, or book.

The QuickHelp.strings can be either a “plain text” strings file, or a property list.

A “plain text” strings file contains list of key-value pairs along with optional comments describing the purpose of each key-value pair. Key and value strings are separated by an equal sign (=), and the entire entry must be terminated with a semicolon character (;). By convention, comments are enclosed inside C-style comment delimiters (/* and */) and are placed immediately before the entry they describe.

```
/* Comment for translation */
```
```
"Key"="Value";
```

A property list strings file contains a top-level dictionary containing keys with string values.

```
<?xml version="1.0" encoding="UTF-8"?>
```

<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">

```
<plist version="1.0">
```
```
<dict>
```
```
<key>Key</key>
```
```
<string>Value</string>
```
```
</dict>
```
```
</plist>
```

For more information, see String Resources in Resource Programming Guide.

Playground Example

        /**
 Flips a table
 - Parameter times: Number of times to flip a table
 - LocalizationKey: my-playground-flip-table
 */
func flipTable(times: Int = 1) {
    let minTimes = max(times, 1)
    for _ in 0 ..< minTimes {
        print("(╯°□°)╯( ┻━┻") }
}
}

      

Listing 35-1BookName.playgroundbook/PrivateResources/es.lproj/QuickHelp.strings

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>my-playground-flip-table</key>
<string>Voltea la mesa
- Parameter times: Número de veces para voltear una mesa
</string>
</dict>
</plist>

When Quick Help is consulted on a device set to a English-speaking locale, the original content is presented.

image: Art/MFR_symbol_section_localizization_key_en_2x.png

When Quick Help is consulted on a device set to a Spanish-speaking locale, the localized content is presented.

image: Art/MFR_symbol_section_localizization_key_es_2x.png