Skip to main content
Version: 2.x.x

Frequently Asked Questions

This page addresses common questions and misconceptions about the Tolgee CLI.

Key Management and Default Values​

Q: Does the CLI detect duplicate keys with different default values?​

A: No, currently the CLI does not detect this scenario.

If you have the same key with different default values in your code:

<T keyName="save-btn" defaultValue="Save" />
<T keyName="save-btn" defaultValue="Save (Changed)" />

The CLI will not warn you about this conflict. This is a known limitation that may be addressed in future versions.

Workaround: Use consistent default values across your codebase, or rely on the Tolgee Platform as the single source of truth for translations rather than default values in code.

Q: Why don't default values automatically update my base language translations?​

A: This is by design to prevent conflicts between code and platform translations.

When you first sync a key, the default value becomes the base language translation. However, subsequent changes to default values in code will not update the platform translation. This prevents situations where:

  • A developer changes a default value in code
  • A translator or PM has already refined the wording in the platform
  • The two sources of truth conflict with each other

Q: How can I search for strings in my code if I only use keys and not default values?​

A: This depends on your approach to translation management.

If you follow Tolgee's recommended approach of using the platform as the single source of truth:

  • Best approach: Use in-context editing (available only for native JS SDKs with DevTools plugin) to click directly on the string in your app, then search for the key
  • Alternative: Search for keys in your code: grep -r "save-btn" src/, then look up the actual translation in the Tolgee Platform

If you maintain fallback translations in your code:

  • You can search for both keys and translation strings
  • But you'll need to manage consistency between code and platform

Best Practices and Workflow​

Q: Should I keep default values in my code?​

A: Tolgee recommends against using default values as the source of truth.

Here's why:

  • Single source of truth: Having translations in both code and platform creates confusion
  • Team collaboration: PMs, UX designers, and translators can update wording directly in the platform
  • Consistency: Prevents conflicts between developer changes and translator/PM changes

Recommended approach: Use keys without default values, and rely on the Tolgee Platform for all translation content.

Q: How should I handle translations in production?​

A: NEVER use API keys in production. You have two recommended options:

Option 1: Export translations as static assets

  1. Use tolgee pull to download translations to local files during your build process
  2. Bundle these files with your application
  3. Keep these files in version control
  4. Update them regularly via tolgee pull in your CI/CD pipeline

Option 2: Use Tolgee Content Delivery

  • Configure your app to load translations from Tolgee's Content Delivery using the BackendFetch plugin
  • No API keys required in production
  • Automatic updates when translations change (up to 15 minutes for global CDN propagation)

Both approaches give you:

  • No API key exposure in production
  • Reliable performance without direct platform dependency
  • Platform as single source of truth during development

Q: How do I handle the workflow where I want to update translations from code?​

A: Update translations directly in the Tolgee Platform, not in code.

Instead of changing default values in code:

  1. Update the translation in the Tolgee Platform UI
  2. Use the platform's features like translation memory, suggestions, and collaboration
  3. Pull the updated translations to your local files if needed

This workflow:

  • Keeps the platform as the authoritative source
  • Allows non-developers to manage translations
  • Prevents conflicts and inconsistencies

Technical Limitations​

Q: Should I avoid having multiple keys with the same translation text?​

A: No, Tolgee actually recommends against de-duplication of translation strings.

While some developers worry about translating the same phrase multiple times (e.g., having both save-btn and submit-btn keys with the text "Save"), this is actually beneficial because:

  • Context matters: The same text can have different meanings in different contexts
  • Future flexibility: You may want to change the wording in one place but not another
  • Semantic clarity: Keys should represent their purpose, not just their current text

For example, save-document and save-settings might both currently say "Save", but you may later want to change one to "Save Document" while keeping the other as "Save".

Q: Can I force the CLI to update base language translations from default values?​

A: No, this is not supported and goes against Tolgee's recommended workflow.

The CLI is designed to treat the platform as the authoritative source for translations. If you need to update base language translations, do so directly in the Tolgee Platform.