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. Available values : android_xml, ios_strings, ios_stringsdict, ios_xcstrings, java_properties, rails_yaml, angular_xlf, 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
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`

Items in upload.files and download.files accept additional parameters for multi-locale file types, described in the next section.

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 catalogs, for example Localizable.xcstrings and InfoPlist.xcstrings. Since they all share the same Localizely project, tags decide which string keys belong to which file. For this purpose, items in upload.files accept tag_added, tag_updated, and tag_removed, 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.

When more than one file is listed, each item in upload.files must define tag_added and each item 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.
Upload tags only the string keys that it adds, updates, or removes. String keys that already exist in Localizely and stay unchanged need to be tagged in Localizely, so that they end up in the right file.
These file-level parameters are available only for multi-locale file types. For other file types, use upload.params and download.params.

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_added: # Tags added to new string keys from this file
        - localizable
    - file: MyApp/InfoPlist.xcstrings
      tag_added:
        - 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

Configuration file

Documentation

Introduction

Full configuration

Multi-locale file types

Several files in one repository

Documentation

About

Resources

Free tools

Boring stuff

Newsletter