Options

Last modified: July 19, 2022Author: Jakub Pomykała

To offer a wide-range of compatibility with different localization tools and software, SimpleLocalize offers a variety of auto-translation, import and export options to meet all your requirements.

Table of contents

Auto-translation options

Export/download options can be used in web interface in auto-translation popup, and API auto-translation job.

FORCE_REPLACE

By default, only not translated strings (empty text) are translated to speed up the auto-translation process. This option forces SimpleLocalize to auto-translate all existing translations for a given language. Using this option consumes your auto-translation limit! Information about current auto-translation usage is available in your account settings page.

AUTO_PUBLISH

By default, after a successful auto-translation job, translations are available in translation editor ('Translations' tab). Enabling this option adds the additional step to the auto-translations process, which is a CDN publication. After a successful auto-translation, translations will be published in the latest CDN environment. From there, you can push them into a Production environment in 'Hosting' tab.

Example 1:

Translation: Hello {firstName}, how are you?

Found variable: {firstName} won't be translated.

Translated into Polish: Witaj {firstName}, jak się masz?

Example 2:

Translation: {var, {my text} other {}} Hello, {user_name}

Found variables: {var, {my text} other {}}, {user_name} won't be translated.

Translated into Polish: {var, {my text} other {}}, Witaj, {user_name}

USE_TRANSLATION_KEYS

By default, only translations from a language are used to translate strings into another language. In some cases, you can use translation keys to translate them into other languages. This option tries to use translation key as a translation source, only if no translation is available. In uses a basic modification before translation. Underscores _ and dashes - are replaced with spaces, translations are trimmed, and texts are capitalized. See example below:

Translation key: MY_TRANSLATION_KEY

Translation source: My translation key

Export options

Export/download options can be used in web export panel in 'Data' tab, CLI download command, and API export file endpoint.

INCLUDE_DESCRIPTIONS

By default, exporting translation to Excel or CSV format, won't contain translation key descriptions. Enabling this option adds a description column with translation key descriptions.

WRITE_NESTED

By default, translations are exported in a flat key-value format. Enabling this option instructs SimpleLocalize to write export translations in a multi-level format, where a key can contain a string or object. Every new level is created on a dot (.). See example below:

Translation keys: navigation.title, navigation.logout, footer.about

Without WRITE_NESTED option

{
  "pl": {
    "navigation.title": "Tytuł",
    "navigation.logout": "Wyloguj",
    "footer.about": "O nas"
  },
  "fr": {
    ...
  }
}

With WRITE_NESTED enabled

{
  "pl": {
    "navigation": {
      "title": "Tytuł",
      "logout": "Wyloguj"
    },
    "footer": {
      "about": "O nas"
    }
  },
  "fr": {
    ...
  }
}

In some cases, this option may fail, due to incorrect translation key values. For example, having keys:

  • navigation.title = 'Title'
  • navigation = 'Navigation'

will result an error, because JSON file cannot contain key duplicates like below:

{
  "pl": {
    "navigation": {
      "title": "Title"
    },
    "navigation": "Navigation"
  }
}

ESCAPE_NEW_LINES

By default, Simplelocalize is not making any modifications of translation text or files during the import unless it is crucial for correct reading of the text. This option replaces native new lines (those from translation editor) with '\n' characters in exported CSV files. See example below:

translation texts with line breaks

In translation input above, there are 3 line breaks which have been made by a translator by clicking 'Enter' button. Whenever you will export translation into a CSV format, those enter will be held.

Without ESCAPE_NEW_LINES option

"FACEBOOK.SHARE","Share","Partager","Udział"
"FOOTER.ABOUT","It is a long-established fact that a reader will be distracted by the readable content of a 
page when looking at its layout. The point of using Lorem Ipsum is that it has a 
more-or-less normal distribution of letters, as opposed to using 'Content here, 
content here', making it look like readable English.","",""
"FOOTER.ADVERT","Press","presse","naciskać"

With ESCAPE_NEW_LINES option

"FACEBOOK.SHARE","Share","Partager","Udział"
"FOOTER.ABOUT","It is a long-established fact that a reader will be distracted by the readable content of a \npage when looking at its layout. The point of using Lorem Ipsum is that it has a \nmore-or-less normal distribution of letters, as opposed to using 'Content here, \ncontent here', making it look like readable English.","",""
"FOOTER.ADVERT","Press","presse","naciskać"

All linebreaks have been replaced by a new line \n character.

ONLY_TRANSLATED

By default, all translations and translation keys are exported regardless of the translation status. Enabling ONLY_TRANSLATED option will export only translation keys that has a non-empty translation strings.

Default output

{
   "navigation.title": "Title",
   "navigation.logout": ""
}

With ONLY_TRANSLATED

{
   "navigation.title": "Title"
}

ONLY_NOT_TRANSLATED

By default, all translations and translation keys are exported regardless of the translation status. Enabling ONLY_NOT_TRANSLATED option will export only translation keys that has an empty or missing translation strings.

Default output

{
   "navigation.title": "Title",
   "navigation.logout": ""
}

With ONLY_NOT_TRANSLATED

{
   "navigation.logout": ""
}

Import options

Import/Upload options can be used in a web import panel in 'Data' tab, CLI upload command, and API import file endpoint.

PUBLISH_AFTER_IMPORT

By default, after a successful import, translations are visible in translation editor ('Translations' tab). Enabling this option adds the additional step to the import process, which is CDN publication. After a successful import, translations will be published in the latest CDN environment. From there, you can push them into a Production environment in 'Hosting' tab.

REPLACE_TRANSLATION_IF_FOUND

By default, import only imports new translations (empty text) and new translation keys with translations. Enabling this option allows SimpleLocalize to also update existing translations. Translations which are NOT present in the imported file will stay untouched.

DELETE_NOT_PRESENT_KEYS

By default, import only imports new translations (empty text) and new translation keys with translations. Enabling this option removes all existing translation keys, and translations and imports translation keys and translations and languages from a file.

TRIM_LEADING_TRIALING_SPACES

By default, Simplelocalize is not doing modifications of translation strings during the import unless it is crucial for correct reading of the text. Enabling this options removes additional spaces from the beginning and the end of translation text. See example below:

Input: <space><space><space>My translation<space><space>

Output: My translation

UNESCAPE_NEW_LINES

By default, new lines in translations are detected automatically using rules default for the chosen format. Enabling this option allows you to replace new line characters (\n) in translation texts into a native new-lines. See example below:

Fragment of CSV file with '\n' characters as new lines.

"FACEBOOK.SHARE","Share","Partager","Udział"
"FOOTER.ABOUT","It is a long-established fact that a reader will be distracted by the readable content of a \npage when looking at its layout. The point of using Lorem Ipsum is that it has a \nmore-or-less normal distribution of letters, as opposed to using 'Content here, \ncontent here', making it look like readable English.","",""
"FOOTER.ADVERT","Press","presse","naciskać"

File imported with UNESCAPE_NEW_LINES translations when unescaping enabled

File imported without UNESCAPE_NEW_LINES translations when unescaping disabled