Source Code

genstrings scans the provided source files for calls to the following functions, to extract their string contents and produce string tables for localization. The NSLocalizedString() macro is used as an example below; by default genstrings recognizes it and the CFCopyLocalizedString() macro.

To enable support for the SwiftUI Text() initializer, use the -SwiftUI flag.

See the documentation for the -s routine option below for information on how to recognize other patterns.

The "key", "Table", and "value" arguments must be literal strings in order for genstrings to be able to extract them from source code. The comment argument may be either a literal string or nil, but is strongly recommended to provide context to localizers.

NSLocalizedString("key", comment)

Source lines containing this form will generate an appropriate string table entry to a file named Localizable.strings.

NSLocalizedStringFromTable("key", "Table", comment)

NSLocalizedStringFromTableInBundle("key", "Table", bundle, comment)

Source lines containing either of these forms will generate an appropriate string table entry in a file named Table.strings.

NSLocalizedStringWithDefaultValue("key", "Table", bundle, "value", comment)

Source lines with will generate an appropriate string table entry in a file named Table.strings with a distinct key and value; all other forms reuse the key as the value.

Format Strings and Positional Parameters

Keys and values of string file entries can include formatting characters. For value strings with multiple formatting arguments, positional parameters are generated. These allow the order of arguments to be changed as needed by each localization. For example, "File %1$@ contains %2$d bytes." could become "%2$d bytes are contained in file %1$@." in another localization.

The -noPositionalParameters flag can be used to suppress generation of positional parameters in string table entries.

Important When a macro such as NSLocalizedString() is used as a format string, it is crucial to ensure that all formatting arguments are present with the same types in the same order in any translated string tables, to avoid runtime argument type mismatches.

Encoding

By default, genstrings assumes source files are UTF-8 encoded, or contain no non-ASCII characters. Files in other encodings will not be read successfully unless the -encoding charset-name flag is used to specify their encoding as an IANA charset name. The -macRoman flag can also be used to specify input file are expected to be in the Mac Roman encoding. However, developers are strongly encouraged to move to UTF-8 as the encoding for source files as the -macRoman option may be removed in future versions.

The -d flag may be used to request genstrings attempt to detect an input file's encoding if it is not read successfully as UTF-8 or using its specified encoding.

Embedded non-ASCII characters in UTF-8 files, as well as non-ASCII characters specified by the escape sequences \uxxxx and \Uxxxxxxxx are read automatically by genstrings. The -u option and genstrings specific escape sequence are also supported.

Generated .strings files are UTF-16 encoded by default. Host endianness is used unless the -bigEndian or -littleEndian option is specified. The endian options do not affect .strings files being appended to with the -a option. The byte order of the existing file is maintained.