chore: Translation Keys section updated with better descriptions and headers

platform/translation_keys/batch_operations.mdx

@@ -2,15 +2,15 @@
 id: batch_operations
 title: Batch Operations
 sidebar_label: Batch Operations
-image: /img/og-images/platform.png
+image: /img/og-images/platform.png
 ---
 
 import { ScreenshotWrapper } from '../shared/_ScreenshotWrapper';
 
 Batch operations allow you to perform one operation on multiple keys at once.
 This is useful for performing operations on many keys, such as deleting all keys in a namespace or machine translating all keys in a project.
 
-## Selecting keys
+## Select Keys for Batch Operations
 
 First, select the keys you want to perform the batch operation on. You can do this by **selecting the checkbox next to the keys** you want to select.
 
@@ -26,7 +26,7 @@ Next, you can select the batch operation you want to perform from the dropdown l
   alt="Select keys"
 />
 
-## Available batch operations
+## Available Batch Operations
 
 - **Machine translation** – When you pick this operation, you will be prompted to select languages to translate into.
   The [primary Machine translation providers](/platform/projects_and_organizations/machine-translation-settings) chosen for the languages will be used to translate the keys.

platform/translation_keys/custom_values.mdx

@@ -10,7 +10,7 @@ are added by Tolgee when importing data.
 
 The custom values are also available when accessing the data via REST API via the `custom` field on the translation key.
 
-## Editing custom values
+## Edit Custom Values
 To edit custom values
 1. Go to translations view
 2. Click the key name to open the `Edit Key` dialog
@@ -23,6 +23,6 @@ import { ScreenshotWrapper } from "../shared/_ScreenshotWrapper";
 
 
 
-## Tolgee internal Custom Values
+## Tolgee Internal Custom Values
 The custom values prefixed by the `_` character are used by Tolgee and have special meaning.
 For example, `_flutterArbPlaceholders` is used to store placeholder metadata for Flutter, and it's used when exporting data to flutter arb format.

platform/translation_keys/keys.mdx

@@ -6,26 +6,28 @@ image: /img/og-images/platform.png
 ---
 import { ScreenshotWrapper } from "../shared/_ScreenshotWrapper";
 
-Translation keys are used to identify a string or text that is displayed to the user.
-They are used in the translation files to translate the text to the user's language. They are also used in the code to display the text to the user.
+Translation keys identify a string or text that is displayed to the user.
+They are used in the translation files to translate the text to the user's language and in the code to then display it.
 
 Example of a translation key:
 
 ```text
 settings.account-security.mfa.disable-mfa
 ```
 
-## Adding translation keys to Tolgee
+## Add Translation Keys to Tolgee
 
 To add new translation keys to Tolgee, you have a few options:
 
 - [Import](/platform/projects_and_organizations/import) a new translation file.
-- Use the editor to [create a single translation key](#creating-translation-keys-manually) and adjust its options as needed.
+- Use the editor to [create a single translation key](#create-translation-keys-manually) and adjust its options as needed.
 - Use the [Tolgee API](/api) to add one or more keys through the [`create` endpoint](/api/create-6).
 - Use the [Tolgee CLI](/tolgee-cli) to add one or more keys with the [`push` command](/tolgee-cli/push-pull-strings#pushing-strings).
 - Use the [Tolgee Figma plugin](/platform/integrations/figma_plugin/setup) to add one or more keys with the [`Push` action](/platform/integrations/figma_plugin/usage#push-adding-new-strings-and-translations).
 
-## Creating translation keys manually
+## Create Translation Keys Manually
+
+If the previous options for adding translation keys automatically do not suit your needs and you want to add them directly on the platform, you can do so manually. This is often the case when you want to create the key first and adjust its options before beginning the implementation.
 
 To create a new translation key, click the `+ Add` button on the project's Translations view.
 
@@ -48,7 +50,7 @@ You can select which languages to show here by selecting them in the dropdown at
   src="/img/docs/platform/create_key_form.webp"
 />
 
-## Naming conventions
+## Translation Key Name Conventions
 
 When it comes to naming conventions for translation keys, there are no hard and fast rules.
 However, it is generally advisable to use naming conventions that are easy to understand and follow a consistent format. Here are some common naming conventions that can be used for translation keys:
@@ -69,7 +71,7 @@ If you want to learn more about naming translation keys, check out our [blog pos
 :::
 
 
-## Key description
+## Key Description
 Key descriptions can help translators to understand the context of the key. It's also provided to the
 [Tolgee AI translator](/platform/translation_process/ai_translator) to help it understand the key.
 

platform/translation_keys/namespaces.mdx

@@ -7,49 +7,56 @@ image: /img/og-images/platform.png
 
 import { ScreenshotWrapper } from '../shared/_ScreenshotWrapper';
 
-Especially when managing more extensive projects, storing all keys in a single localization file can be insufficient. That's where namespaces come into play.
-This feature enables you to structure keys into different namespaces. When Tolgee exports a project with namespaces, Tolgee stores the namespace data to separate files.
+Storing all keys in a single localization file can be insufficient (especially when managing more extensive projects). That's where namespaces come into play.
+When Tolgee exports a project with namespaces, Tolgee stores the namespace data to separate files.
 
 In the Translations view, namespaces are displayed on the top of each namespace group.
 
-## Selecting namespaces for a new key
+## Assign a Namespace to a New Key
 
-To select namespace while creating a new key
+Namespaces help to organize translation keys by context or responsibility, such as:
+-	feature or module (auth, checkout, settings)
+-	application area (common, errors, emails)
+-	platform (web, mobile, admin)
+
+To assign a namespace while creating a new key:
 
 1. Click `+ Add` in the top right of the Translations view
 2. Select the namespace in the `namespace` dropdown
    - If the desired namespace doesn't exist yet, fill in the namespace name in the dialog and click the `+` icon on the right to create it.
 
-## Filtering by namespace
+## Filter by a Namespace
+
+Filtering by a namespace gives you the option to see only the keys from the selected namespace. This way, you won’t confuse keys from different parts of the app.
 
 There are two ways how to filter keys by namespaces.
 
-### Using filter dropdown
+### Using Filter Dropdown Menu
 
 1. Click the `Filter...` dropdown in the Translations view
 2. Click `Namespaces`
 3. Select one or multiple namespaces
 
-### Using the namespace banner
+### Using the Namespace Banner
 
 1. Click the namespace banner on top of namespace key group
 2. Select `Filter by namespace`
 
-## Renaming namespaces
+## Rename a Namespace
 
 1. Click the filter banner on top of namespace key group
 2. Select `Rename namespace`
 3. Set a new name in the dialog
 4. Click rename
 5. Confirm the operation
 
-## Deleting namespace
+## Delete a Namespace
 
 Tolgee deletes namespaces automatically when there is no key assigned to them.
 
 To delete a namespace, just delete all keys in the namespace.
 
-## Exporting keys by namespaces
+## Export Keys by Namespaces
 
 When exporting keys, you can select which namespaces should be exported. If you don't select any namespace, all keys will be exported.
 

platform/translation_keys/screenshots.mdx

@@ -2,15 +2,15 @@
 id: screenshots
 title: Screenshots
 sidebar_label: Screenshots
-image: /img/og-images/platform.png
+image: /img/og-images/platform.png
 ---
 
 import { ScreenshotWrapper } from '../shared/_ScreenshotWrapper';
 
-Screenshots are a great way to help translators to better understand what they should translate and provide them with more context.
-You can add screenshots to your keys and use them in the translation process.
+Screenshots are a great way to help translators better understand what they should translate and provide them with more context.
+You can add screenshots to your keys and use them in the translation process to improve translation quality.
 
-## Adding screenshots
+## Add Screenshots to Keys
 
 To add screenshot to an existing key, click the `Screenshots` button in the key detail:
 
@@ -21,7 +21,7 @@ To add screenshot to an existing key, click the `Screenshots` button in the key
 
 After you click on the button, you can select the screenshot you want to upload or drag and drop the screenshot to the upload form.
 
-## Using screenshots in translation
+## Using Screenshots in Translation
 
 When you are translating your key, you can click the `Screenshots` button in the key detail and click on the the screenshot to see it in the modal window.
 
@@ -30,7 +30,9 @@ When you are translating your key, you can click the `Screenshots` button in the
   alt="key view screenshot"
 />
 
-## Deleting screenshots
+Sreenshots can also be used with AI translation as additional context for higher translation accuracy.
+
+## Deleting Screenshots
 
 You can delete screenshot from the key detail. To do so, click on the `X` button in the screenshot detail.
 

platform/translation_keys/tags.mdx

@@ -2,16 +2,16 @@
 id: tags
 title: Tags
 sidebar_label: Tags
-image: /img/og-images/platform.png
+image: /img/og-images/platform.png
 ---
 
 import { ScreenshotWrapper } from '../shared/_ScreenshotWrapper';
 
-Tolgee allows you to manage tags in the application – you can create, assign them to keys and filter for them in the Translation view.
+Tags help group translation keys for easier work and batch operations on multiple keys within a specific group. Tolgee allows you to create tags, assign them to keys, and filter by them in the Translation view.
 
 With tags, you cannot selectively export a particular set of keys like you can with [namespaces](namespaces).
 
-## Creating and assigning tags
+## Create and Assign Tags
 
 To assign a tag to a key, click the `+ tag` icon on the key in Translations view:
 
@@ -24,17 +24,17 @@ Then you can **assign an existing tag or create a new one** by typing the name a
   alt="add new tag to key"
 />
 
-## Filtering by tags
+## Filter by Tags
 
 There are two ways how to filter keys by tags.
 
-### Using filter dropdown
+### Using Filter Dropdown
 
 1. Click the `Filter...` dropdown in the Translations view
 2. Click `Tags`
 3. Select one or multiple tags
 
-### Clicking on tag
+### Click on a Tag to Filter
 
 1. Click the tag in a key
 2. The tag will be automatically added to the filtering and the keys will be filtered by it