How to manage translation file versioning with tags

Versioning is one of the trickiest parts of managing translation files. Each new release introduces fresh strings, updates old ones, and sometimes retires keys altogether. Without a clear strategy, it's easy to lose track of what belongs where, especially when collaborating with multiple translators and developers.

That's where translation key tags in SimpleLocalize come in. Tags are a simple but powerful way to track changes, organize keys, and keep your translation files under control, no matter how many versions or languages you are managing.

In this post, we'll show you how to use translation key tags in SimpleLocalize as a lightweight versioning system. (If you are new to tags, check out our introductory post on translation editor tags first.)

What are translation key tags?

Translation key tags are customizable, color-coded labels you can assign to translation keys in your project. Think of them as sticky notes that help you mark and organize keys.

You can use tags to:

• Group keys by feature (e.g., Checkout, Dashboard)
• Track keys by version (e.g., Beta, v1.0, v2.0)
• Highlight priority (e.g., High Priority, Low Priority)
• Control access (e.g., Internal, Public)

Tags show up right next to your keys in the SimpleLocalize translation editor, so you can filter and find exactly what you need in seconds.

Why use tags for versioning?

Traditional version control systems (like Git) are great for code but don't provide translators with the context they need. Tags in SimpleLocalize bridge this gap:

• Clearly mark which keys belong to which release version.
• Highlight outdated or changed keys that need review.
• Filter and export translations per version for easier release management.
• Improve collaboration between developers, translators, and product teams.

Setting up a tagging workflow

To get started, create version-specific tags in your project settings. For example:

• v1.0 for the initial release
• v1.1 for minor updates
• v2.0 for major overhauls
• Legacy for keys that are still needed for backward compatibility

Applying version tags

When you add or update translation keys, assign the appropriate version tag. Here's a simple workflow you can adopt:

1. Tag new keys by release. Whenever developers introduce new strings for an upcoming version, add the relevant version tag (e.g., v1.1).
2. Mark updated keys for review. If an existing string changes in the source language, other translations are marked as needing review.
3. Retire old keys. For removed strings, swap their version tag for a Legacy tag. This keeps history intact without cluttering active releases.
4. Combine tags with features. Add feature-level tags like Checkout, Profile, or Onboarding alongside version tags. This way, you can filter by both release and feature when preparing updates.

Keeping this workflow consistent ensures everyone on your team knows how to manage translation versions effectively.

Filtering and exporting by tags

When working in the translation editor, you can easily filter keys by their version tags:

Combine filters (e.g., v2.0 + Onboarding + Needs review status) to focus on translations that require attention.

When it's time to export translations for a specific release, in Data > Export, select the desired tags to export only the relevant translations for that release.

You can export translations by tags also using our CLI download or API export, making it easy to integrate into your deployment pipeline.

Bonus: Combine tags with GitHub integration

If you use our GitHub integration, you can automate tagging based on pull requests. For example, when a PR is merged for a new feature or version, you can set up rules to automatically tag the associated translation keys. This reduces manual work and ensures consistency.

If you already manage your translation files in GitHub, you can combine it with tags in SimpleLocalize for a complete versioning workflow.

• GitHub handles file history: every commit keeps a record of changes to your translation files.
• SimpleLocalize tags provide context: easily see which keys belong to which release and their status.
• Together, they ensure developers and translators stay in sync: code is versioned in GitHub, while translations are organized and review-ready in SimpleLocalize.

Learn more about the SimpleLocalize GitHub integration.

Best practices for version tagging

When using tags for versioning, keep these best practices in mind:

• Be consistent: Stick to a naming convention: use consistent labels (vX.Y) across projects.
• Plan your cleanup: Periodically move outdated version tags into Legacy to avoid clutter.
• Document your tagging rules: Make sure developers and translators know when and how to apply tags.
• Use color coding: Assign distinct colors to different version tags for quick visual identification.
• Leverage filters: Regularly use tag filters to review and manage translations before releases.
• Use bulk actions: Take advantage of SimpleLocalize's bulk tagging features to quickly update multiple keys at once.

Conclusion

Translation key tags aren't just for organizing by features or teams, they are a powerful tool for managing translation file versioning. With a solid tagging strategy, you will know exactly which strings belong to which release, making it easier to coordinate updates, reviews, and exports.

Try introducing version tags in your next release cycle, and see how much easier it becomes to manage translations across versions.

Happy tagging!