Apple String Catalog is the latest Apple approach to localization for Apple platforms. We recommend using it in favor of XLIFF since this format gives you better control over the strings and their translations.

Tolgee supports simple values as well as plural values.

Example of a Stringsdict file:

{
  "sourceLanguage": "en",
  "version": "1.0",
  "strings": {
    "dog_count": {
      "localizations": {
        "en": {
          "variations": {
            "plural": {
              "other": {
                "stringUnit": {
                  "state": "translated",
                  "value": "I have %lld dogs."
                }
              }
            }
          }
        },
        "cs": {
          "variations": {
            "plural": {
              "one": {
                "stringUnit": {
                  "state": "translated",
                  "value": "Já mám jednoho psa."
                }
              },
              "few": {
                "stringUnit": {
                  "state": "translated",
                  "value": "Já mám %lld psi."
                }
              },
              "other": {
                "stringUnit": {
                  "state": "translated",
                  "value": "Já mám %lld psů."
                }
              }
            }
          }
        }
      }
    },
    "hello": {
      "en": {
        "stringUnit": {
          "state": "translated",
          "value": "Hello!"
        }
      },
      "localizations": {
        "cs": {
          "stringUnit": {
            "state": "translated",
            "value": "Ahoj!"
          }
        }
      }
    }
  }
}

We recommend using the semantic keys format as in the examples above. That enables you to change the base values without modifying the key and doesn't suggest keeping the keys in sync with the base language translation.

The MessageFormat and placeholder conversion

When importing data to Tolgee from the Apple .strings and .stringsdict files, you can either enable or disable the conversion to the Tolgee Universal ICU placeholders. The conversion is enabled by default. You can also disable the conversion globally in the project settings. We recommend keeping the conversion enabled, as it brings many benefits. Read more about the benefits of Tolgee Universal ICU placeholders.

When the conversion is disabled, the original placeholders (e.g., %llm, %@). are preserved. The message format is automatically detected when importing data in Apple .strings and .stringsdict format. When exporting, you can choose from message & placeholder formats listed above.

Placeholder conversion specification

The official Apple's string format specifiers documentation can be found here.

Only specifiers specified in the table below are supported. Tolgee doesn't support additional flags and modifiers and placeholders using them are not converted.

Specifier	ICU type	Example	Converted to ICU	Note
%	N/A	%%	%	%% is the way how to render %, in ICU we don't have such concept, so we just add %. When exporting, the % is converted back to %%.
@	none	%@	{0}
lld	number	%lld	{0, number}
f	number, [precision string]	%f	{0, number, 0.000000}	By default %f uses 6 decimal places, that's why we convert it to the number with such precision. %.2 f would be {0, number, 0.00} and so on.
e	number, scientific	%e	{0, number, scientific}	%E is not supported

If your placeholder is not supported, you can use %@ and format the string yourself in the code.

Apple also supports n$ positional specifiers. There are converted to as well as the zero based argument index. E.g. I am %2$@, and I have %1$lld dogs. is converted to I am {1} and I have {0, number} dogs.

Importing / Exporting in general

To read more about importing and exporting with Tolgee, continue to import section or export section.

Using with the CLI

Apple String Catalog (.xcstrings) format differs slightly from other formats because it contains all the languages in a single file.

You will probably want to push only the base language (usually English) since translating other languages will happen in the Tolgee Platform. That's why we set the push.languages to ["en"], so Tolgee will ignore all other languages included in the .xcstrings.

For pulling, you usually want to use all the languages from the Tolgee platform, so we are keeping the default for the pull option.

{
  "$schema": "https://docs.tolgee.io/cli-schema.json",
  "projectId": 123,           // project id in tolgee platform
  "format": "APPLE_XCSTRINGS",
  "push": {
    "filesTemplate": "./i18n/Localizable.xcstrings",
    "languages": ["en"]       // which languages should be pushed by default
  },
  "pull": {
    "path": "./i18n"
  }
}

Read more about CLI