docs: add CLI FAQ and document key management limitations

sidebarTolgeeCli.js

@@ -18,5 +18,6 @@ module.exports = {
       ],
     },
     'migration-to-v2',
+    'faq',
   ],
 };

tolgee-cli/extraction/syncing-strings.mdx

@@ -35,6 +35,31 @@ When running this command on CI, the CLI automatically adds review annotation wa
 See an example [here](https://github.com/tolgee/tolgee-platform/commit/ddfff41#diff-84dc9ca52993f2d66eda975f622361460f83d659ce6ddf1a0c086e6ca8c328ccR46).
 :::
 
+### Duplicate key detection limitations
+
+Currently, the CLI does **not** detect when the same key appears multiple times in your code with different default values. For example, if you have:
+
+```jsx
+<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.
+
+### Default values and base language behavior
+
+When you first sync a key with a default value, the CLI will create the key in your Tolgee project and set the default value as the translation for your base language. However, **subsequent changes to default values in your code will not automatically update the base language translation** in Tolgee.
+
+For example:
+1. You add `<T keyName="welcome" defaultValue="Welcome" />` and run `tolgee sync`
+2. Tolgee creates the key "welcome" with "Welcome" as the English (base language) translation
+3. Later, you change the code to `<T keyName="welcome" defaultValue="Welcome Back" />`
+4. Running `tolgee sync` again will **not** update the English translation to "Welcome Back"
+
+This is by design to prevent conflicts between code changes and translations managed in the Tolgee Platform.
+
 ## Comparing projects
 
 You can think of this utility as a dry-run of `tolgee sync`. You can use it to see the added/removed strings and

tolgee-cli/faq.mdx

@@ -0,0 +1,112 @@
+---
+id: faq
+title: 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:
+
+```jsx
+<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.

tolgee-cli/introduction.mdx

@@ -13,6 +13,25 @@ You can find the **source code** of the CLI on [GitHub](https://github.com/tolge
   <source src="/tolgee-cli.webm"></source>
 </video>
 
+## Best Practices
+
+### Single Source of Truth
+
+Tolgee recommends using the **Tolgee Platform as the single source of truth** for all translations, rather than maintaining default values in your code. This approach:
+
+- **Prevents conflicts** between code changes and translator/PM updates
+- **Enables collaboration** - non-developers can manage translations directly
+- **Maintains consistency** across your entire localization workflow
+
+### Recommended Workflow
+
+1. **Extract keys without default values** from your code using the CLI
+2. **Manage all translation content** in the Tolgee Platform
+3. **Use `tolgee pull`** to download translations as local fallback files
+4. **Keep fallback files in version control** for offline functionality
+
+This workflow decouples translation content from code, allowing your team to iterate on wording without requiring code changes.
+
 ## Features
 
 ### Easy project configuration