Options

Last updated: October 26, 2023Author: Jakub Pomykała

To offer a wide-range compatibility with different localization tools and software, SimpleLocalize offers a variety of auto-translations, 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/Download options

Export/download options can be used in a 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.

This option is valid only for: excel, csv-translations, java-properties formats.

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 naming. For example, having keys:

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

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

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

This option is valid only for: single-language-json, multi-language-json, module-exports, php-array formats.

ESCAPE_SINGLE_QUOTES

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 one single quote ' with two single quotes '' in exported files.

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/Upload 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_TRAILING_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_SINGLE_QUOTES

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 two single quotes '' with one single quote '.

If the translation text contains an odd number of single quotes next to each other, the last one will be left untouched.

This option is valid only for: java-properties

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

UPDATE_ORDER

By default, translation keys order is not updated during the import. Enabling this option allows you to update translation keys order in the translation editor based on the order in the imported file. Please note, that this option may extend the import time for large files, and it won't work properly for multi-file imports.

UPDATE_DESCRIPTIONS

By default, during the SimpleLocalize CLI imports, translation key descriptions are set as code descriptions. You can change this behavior by using this option. This option will update and replace the translator translation key descriptions if they are present in the imported file.