Configuration file

Introduction

GitHub, GitLab, and Bitbucket integrations use a configuration file that describes how to link your translation files in the git repository with your Localizely project. Furthermore, the Localizely CLI tool also uses this configuration file, allowing easy synchronization of localization files between your project and Localizely.

The file should have a name localizely.yml and usually should be in the root folder of the project.

Full configuration

config_version: 1.0 # Required. Only 1.0 available
project_id: c776c33e-f428-4c91-87e1-a6a18c1554fe # Required. Your project ID from: https://app.localizely.com/projects
file_type: flutter_arb # Required, unless every item in upload.files and download.files sets its own file_type. Available values : android_xml, ios_strings, ios_stringsdict, ios_xcstrings, java_properties, rails_yaml, angular_xlf, xliff, flutter_arb, dotnet_resx, po, pot, json, csv, xlsx
branch: main # Optional. Your branch in Localizely project to sync files with.
upload: # Required.
  files: # Required. List of files for upload to Localizely. Usually, it is just one file used for the main locale
    - file: lib/l10n/intl_en.arb # Required. Path to the translation file
      locale_code: en # Required, except for ios_xcstrings where it must be omitted. Locale code for the file. Examples: en, de-DE, zh-Hans-CN
  params: # Optional.
    overwrite: true # Optional, default: false. If the translation in a given language should be overwritten with modified translation from uploading file.
    reviewed: false # Optional, default: false. If uploading translations, that are added, should be marked as Reviewed. For uploading translations that are only modified it will have effect only if overwrite is set to true. For ios_xcstrings, leave it unset to take the review state from the file.
    tag_added: # Optional. List of tags to add to new translations from uploading file.
      - added
    tag_removed: # Optional. List of tags to add to removed translations from uploading file.
      - removed
    tag_updated: # Optional. List of tags to add to updated translations from uploading file.
      - updated
    tag_in_file: # Optional. List of tags to add to every string key in the uploading file and to remove from the string keys of the branch that are not in it. One tag per platform routes string keys to the right download.
      - android
    placeholder_format: icu # Optional. Placeholder syntax of the file, only for projects with universal placeholders and generic file types (json, java_properties, csv, xlsx, angular_xlf, xliff). Available values : `printf_java`, `printf_ios`, `printf_c`, `icu`, `dotnet`, `ruby`, `i18next`, `raw`. Defaults to the project setting.
download: # Required.
  files: # Required. List of files for download from Localizely.
    - file: lib/l10n/intl_en.arb # Required. Path to the translation file
      locale_code: en # Required, except for ios_xcstrings where it must be omitted. Locale code for the file. Examples: en, de-DE, zh-Hans-CN
    - file: lib/l10n/intl_de.arb # Required. Path to the translation file
      locale_code: de # Required, except for ios_xcstrings where it must be omitted. Locale code for the file. Examples: en, de-DE, zh-Hans-CN
  params:
    export_empty_as: empty # Optional, default: empty. How you would like empty translations to be exported. Allowed values are `empty` to keep empty, `main` to replace with the main language value, or `skip` to omit.
    exclude_tags: # Optional. List of tags to be excluded from the download. If not set, all string keys will be considered for download.
      - removed
    include_tags: # Optional. List of tags to be downloaded. If not set, all string keys will be considered for download.
      - new
    java_properties_encoding: utf_8 # Optional, default: latin_1. (Only for Java .properties files download) Character encoding. Available values : `utf_8`, `latin_1`
    placeholder_format: icu # Optional. Placeholder syntax of the file, only for projects with universal placeholders and generic file types (json, java_properties, csv, xlsx, angular_xlf, xliff). Available values : `printf_java`, `printf_ios`, `printf_c`, `icu`, `dotnet`, `ruby`, `i18next`, `raw`. Defaults to the project setting.

Items in upload.files and download.files accept additional file-level parameters, described in the sections below.

Multi-locale file types

Most file types keep one locale per file, so each item in upload.files and download.files pairs a file with a locale_code. Apple String Catalogs (ios_xcstrings) keep all locales in a single file instead. For this file type, list the catalog file without a locale_code.

On upload, Localizely imports every locale from the file that exists in the project branch and skips the others. Unless upload.params.reviewed is set, the review state of each translation is taken from the file: a string in the translated state is marked as Reviewed, while a string in the needs_review state is not. On download, Localizely writes all locales of the project branch into the file. If the file already exists in the repository, it is updated in place, keeping plurals, device variations, substitutions, and metadata, so only actual translation changes end up in the diff.

Here is a minimal configuration file for an iOS project with a single String Catalog:

config_version: 1.0
project_id: c776c33e-f428-4c91-87e1-a6a18c1554fe
file_type: ios_xcstrings
upload:
  files:
    - file: MyApp/Localizable.xcstrings # No locale_code, the file contains all locales
download:
  files:
    - file: MyApp/Localizable.xcstrings

Several files in one repository

A repository can hold several files that share one Localizely project, for example Localizable.xcstrings and InfoPlist.xcstrings, or the Android and iOS files of one app. Tags decide which string keys belong to which file. For this purpose, items in upload.files accept tag_added, tag_updated, tag_removed, and tag_in_file, while items in download.files accept include_tags and exclude_tags. A file-level parameter overrides the same parameter from upload.params or download.params for that file only.

tag_in_file is the simplest way to route string keys. It adds the tag to every string key in the file and removes it from the string keys of the branch that are not in it, so string keys that already exist in Localizely need no manual tagging. tag_added tags only the string keys that the upload adds, so string keys that already exist and stay unchanged have to be tagged in Localizely.
When more than one file of a multi-locale file type is listed, each of these items in upload.files must define tag_added or tag_in_file, and each in download.files must define include_tags, so that string keys can be routed to the right file.
A file can be listed only once in upload.files and only once in download.files.

Here is a configuration file for an iOS project with two String Catalogs:

config_version: 1.0
project_id: c776c33e-f428-4c91-87e1-a6a18c1554fe
file_type: ios_xcstrings
upload:
  files:
    - file: MyApp/Localizable.xcstrings
      tag_in_file: # Added to every string key in this file, removed from string keys that are not in it
        - localizable
    - file: MyApp/InfoPlist.xcstrings
      tag_in_file:
        - infoplist
download:
  files:
    - file: MyApp/Localizable.xcstrings
      include_tags: # Only string keys with these tags are written to this file
        - localizable
    - file: MyApp/InfoPlist.xcstrings
      include_tags:
        - infoplist

Several platforms in one repository

An item can also set its own file_type, which overrides the top-level one for that file. This lets one repository hold, for example, an Android strings.xml next to an Apple String Catalog. To keep the translations of both platforms in one project, switch the project to universal placeholders, which convert placeholders to the syntax of each file format on upload and download.

Here is a configuration file for an app that ships on Android and iOS:

config_version: 1.0
project_id: c776c33e-f428-4c91-87e1-a6a18c1554fe
upload:
  files:
    - file: android/app/src/main/res/values/strings.xml
      locale_code: en
      file_type: android_xml
      tag_in_file:
        - android
    - file: ios/App/Localizable.xcstrings
      file_type: ios_xcstrings
      tag_in_file:
        - ios
download:
  files:
    - file: android/app/src/main/res/values/strings.xml
      locale_code: en
      file_type: android_xml
      include_tags:
        - android
    - file: android/app/src/main/res/values-de/strings.xml
      locale_code: de
      file_type: android_xml
      include_tags:
        - android
    - file: ios/App/Localizable.xcstrings
      file_type: ios_xcstrings
      include_tags:
        - ios

Previous: CLI

Configuration file

Documentation

Introduction

Full configuration

Multi-locale file types

Several files in one repository

Several platforms in one repository

Documentation

About

Resources

Free tools

Boring stuff

Newsletter