Locize
LoginRegister

Should I use versions or branches?

Both versions and branches help you separate translation work — but they solve different problems.

TL;DR

  • Use versions when you want long-lived “release lanes” (e.g., production vs next, or v1 vs v2) inside the same project.
  • Use branches when you want a short-lived, isolated workspace (e.g., a feature branch, a translation job for an agency) that can be merged back.

Versions

Versions live inside the same Locize project (same project ID), so they are not fully isolated.

Typical use cases:

  • Deployment stages (staging vs production)
  • Product/app releases (v1 vs v2)
  • Long-running parallel development

Versions are usually stable and long-lived — you typically don’t create/delete them every day.

Branches

Branches behave like separate projects (own project ID, own API keys) but they inherit the translation resources from their parent project.

This is useful when you want:

  • A safe, isolated place to work
  • A clear view of what is overridden vs what comes from the parent
  • To invite external people (e.g., translators/agencies) without risking changes in the parent project

Branches typically match code repository branches or dedicated translation jobs. For translator workflows, see: Working with translators.

Overridden values are marked with the state icon overridden and can be filtered by that state:

How overrides work

Overridden values are marked with the “overridden” state icon and can be filtered by that state.

When you publish translations to our CDN (or export using the UI, CLI, or API), the effective result is:

  • Parent translations
  • plus any values overridden in the branch

You can also use the CLI branching features to create, sync and merge branches.

Hint: Because a branch inherits translations from the parent, deleting a key/segment in the branch doesn’t remove the parent value — it will still be visible via inheritance.

How to access translations from the CDN

Branches have their own settings (project ID and API keys). To load translations from the CDN for a branch, use the branch project ID from the branch’s settings.

What about pricing?

Branches are free as long as you don’t exceed the number of words compared to the parent project.

When you merge a branch back into the parent, normal modification costs apply for the changes that are merged.