Documentation section

Release Tags

Learn how to maintain several releases of your translations, and how to merge and manipulate them.

The Release Tags feature allows for maintaining multiple existing releases simultaneously in a similar way as known, e.q., from Docker.

Localazy also comes with extensive functionality for merging and manipulating existing tags.

Latest tag 🔗

All changes are automatically published as the so-called latest tag/version.

Commands like localazy download, localazy list, and localazy cdn work with the latest version by default if not explicitly specified otherwise.

Using the latest ever-changing version in a production or staging environment may not be a good idea, and here come release tags to help.

Publish release tag 🔗

Invoke localazy tag publish staging to create a new tag named staging.

The current state of your project is published under this tag and is accessible by invoking, e.q., localazy download -t staging.

No matter of changes made, the content under this tag is kept unchanged unless you call localazy tag publish staging again (or use merging or promoting tags).

Promoting tags 🔗

While translators and contributors actively translate your project to more languages, you can test your staging tag, and promote it to production by invoking:

localazy tag promote staging production or localazy tag promote staging v1.0

Promoting tag overwrites the old tag or creates a new one and publishes the state from the source tag to it by re-running the whole publishing chain.

It’s possible to promote the tag to itself which effectively re-run the publishing process. This is useful when improvements to our parsers and producers are introduced.

Listing, renaming, deleting tags 🔗

To list all available tags for your project, invoke:

localazy tag list

You can rename tags with:

localazy tag rename {old-tag} {new-tag}

And you can also delete them with:

localazy tag delete {tag-name}

Merging and manipulating tags 🔗

Merging tags allows you to apply translations from the source tag to the target tag. The result of the operation is stored as the output tag.

As it’s highly configurable, you can use it to manipulate the content of the tag - add, remove and change keys and languages.

The invocation of the command has this scheme:

localazy tag merge [parameters] source-tag target-tag output-tag

You can use the same tag both for source-tag and target-tag to manipulate the content only. Also, you can use latest as the source or target to work with the current published translations.

Parameters 🔗

With parameters, you can configure what you want merging to do with your translations and languages:

Parameter Description
--mode MODE Merge mode; default: missing; see below
--no-arrays-checks Merge string arrays even if the merged item doesn’t have the same number of elements as the target tag’s source language item
--different-sources By default, only items with the same source language content for both source and target tag are merged; with this option you can disable this behavior
--add-keys Add string keys missing in the target tag but existing in the source tag
--remove-keys Remove string keys not existing in the source tag
--key KEY Key to merge; can be used multiple times to specify more keys; if not present, all keys are merged
--key-level-separator String used as separator for structured keys; default: ‘.’
--remove-unlisted-keys Remove keys not listed using the --key option
--no-key-prefix Don’t use p: and a: for prefixing plurals and string arrays for the --key option
--update-project Use project information from the source tag; by default, keep information from the target tag
--update-meta Update meta information for string keys; meta information stores additional data for arrays and plurals
--update-languages Change publish/hidden state for languages using information from the source tag
--add-languages Add languages missing in the target tag but existing in the source tag
--languages LANGS Comma-separated list of languages to merge; if not present, all languages in the target tag are merged
--remove-unlisted-languages Remove languages not listed in the --languages option
--remove-missing-languages Remove languages missing in the source tag
--publish-languages LANGS Comma-separated list of languages to change state to published (and not hidden)
--unpublish-languages Comma-separated list of languages to change state to unpublished

Merge modes

Mode Description
none Do not merge keys at all; useful for manipulating languages
missing Merge only strings that are untranslated in the target tag; never touch the source language
update Overwrite all translations in the target tag; never touch the source language
overwrite Overwrite all strings including the source language

Please keep in mind:

  • merging is limited to allowed keys and languages
  • by default, languages existing in the source tag that are not available in the target tag are not merged nor added
  • by default, only strings with the same source language content for both source and target tags are merged (don’t apply for the overwrite mode)

Examples 🔗

Add missing translations from the source tag to the target tag and store as the output tag:

localazy merge source target output

Add language de from source that is missing in target:

localazy merge --add-languages --languages de source target output

Remove all languages and keep only cs, de and en:

localazy merge --languages cs,de,en --remove-unlisted-languages target target output

Update all translations using the latest version:

localazy merge --mode update latest target output

Fix invalid translation of key my_key in language cs:

localazy merge --mode update --key my_key --languages cs latest target output

Unpublish language cs:

localazy merge --mode none --unpublish-languages cs target target output

Add my_key from source that is missing in target:

localazy merge --add-keys --key my_key source target output