feat: Add AI customization docs and blog post (#517)

blog/2024-01-19-releasing-ai-customizations.mdx

@@ -0,0 +1,65 @@
+---
+slug: releasing-ai-customizations
+title: "Elevate Your Translations with AI Translation Customization"
+description: "Enhance your translations effortlessly with Tolgee AI Translation Customization by allowing personalized project descriptions, language notes and key descriptions"
+authors: [mchalupnikova]
+tags: ['tolgee', 'ai', 'tolgee translator']
+image: '/img/blog/ai_customizations.webp'
+---
+In June 2023, we released our own [Tolgee AI Translator](https://tolgee.io/blog/tolgee-ai-translator).
+
+It doesn't ignore context like other traditional machine translators, which makes it great for translating
+especially short texts. Tolgee Translator understands the context of the strings used in your app: that's why
+it can provide the best results.
+
+Throughout autumn 2023, we refined the translator further, including, for example, the language formality feature.
+And now, we are taking another step closer to the [autonomous software translation](https://tolgee.io/blog/autonomous-localization),
+adding a couple of new features, which make the results of Trolgee Translator even more accurate.
+
+We're excited to announce the release of a **new feature, AI Translation Customization**,
+so you can improve the translation by providing a description of your project or adding a language-specific note.
+
+![Ai Customizations](/img/blog/ai_customizations.webp)
+
+<!--truncate-->
+
+:::info
+This functionality is available only in the cloud Business subscription or higher and in subscribed self-hosted instances using the Tolgee AI translator.
+:::
+
+## New Key Features
+Imagine translating an app for golf players. 🏌️
+With AI Translation Customization, you can ensure the tone, terminology, and cultural sensitivity are spot-on.
+AI Translation Customization allows you to tailor your translations in three ways:
+
+### 1. Project Descriptions: Define the overall tone and terminology for your project.
+Project descriptions are beneficial when you have a project in a specific domain. You can also specify your overall tone of voice. For instance, if you're translating an app for golf players, you can provide a description like the following:
+
+Example
+```
+This is an app for golf players.
+We are motivating the players to get better.
+Please use golf terminology.
+Use a friendly tone of voice.
+```
+
+### 2. Language Notes: Specify conventions and tones for specific languages and standardize your terminology.
+Language notes are helpful in specifying your conventions for a specific language. You can also use it to specify common terminology.
+Sometimes, you might also want to specify the tone of voice for a specific language if you wish to communicate differently to different cultures.
+Example for Japanese 🇯🇵
+
+```
+In Japanese, we are using polite language. Japanese Golf players are very polite.
+Always translate "Golf Club" as ゴルフクラブ, referring to the equipment used to hit the ball, not a group of players.
+```
+
+### 3. Key Descriptions: Improve translation accuracy with detailed key descriptions.
+Key descriptions can help translators to understand the context of the key. Key descriptions are also provided to the Tolgee AI translator to help it understand the key.
+You can see the description in the editor directly under the key name.
+
+By completing these three steps, you ensure that the translation results of Tolgee Translator
+will be more precise for your project, and you save some extra reviewing time for your translated texts.
+
+Try AI Translation Customization today and take your translations to a whole new level!
+Explore more details about AI Translation customization in the [documentation](/platform/projects_and_organizations/ai-translation-customization)
+and let us know in the [Tolgee Slack community](https://Tolg.ee/slack) if you have any questions about this new feature.

platform/projects_and_organizations/ai_translation_customization.mdx

@@ -0,0 +1,67 @@
+---
+id: ai-translation-customization
+title: AI Translation Customization
+sidebar_label: AI Translation Customization
+---
+
+import { ScreenshotWrapper } from "../shared/_ScreenshotWrapper";
+
+:::info
+This feature is only available with a Business subscription or higher on Tolgee cloud and on Subscribed Self-hosted
+instances with [Tolgee AI translator](/platform/translation_process/tolgee_translator) enabled as the translation provider.
+:::
+
+If you wish to enhance the results from the [Tolgee AI translator](/platform/translation_process/tolgee_translator),
+you can customize it according to your needs. Tolgee enables you to input key descriptions,
+project descriptions, or language notes. This information is provided along with the actual string
+that requires translation. It helps to understand the context of your translation project and provide
+more accurate translations.
+
+## Providing project description
+
+Project descriptions are beneficial when you have a project in a specific domain.
+You can also specify your **overall tone of voice**.
+For instance, if you're translating an app for golf players, you can provide a description like the following:
+
+```text title="Example"
+This is an app for golf players.
+Please use golf terminology.
+Use a friendly tone of voice.
+We motivate the players to get better.
+```
+
+To provide the project description,
+- Select `Languages` in the project menu.
+- Select `AI Customization`.
+- Click the `+ Description` button in the `Project description` section.
+
+<ScreenshotWrapper
+  alt="Providing project description"
+  src="/img/docs/platform/ai-customization/project-description.webp"
+></ScreenshotWrapper>
+
+## Providing language notes
+
+Language notes are useful to specify your conventions for a specific language. You can also use it to specify common terminology.
+Sometimes, you might also want to specify the tone of voice for a specific language
+if you wish to communicate differently to different cultures.
+
+```text title="Example for Japanese"
+In Japanese, we are using polite language. Japanese Golf players are very polite.
+Always translate "Golf Club" as ゴルフクラブ, referring to the equipment used to hit the ball, not a group of players.
+```
+
+To provide the language description,
+ - Select `Languages` in the project menu
+ - Select `AI Customization`
+ - Click the `+` on the language you want to customize
+
+<ScreenshotWrapper
+  alt="Providing language notes"
+  src="/img/docs/platform/ai-customization/language-notes.webp"
+></ScreenshotWrapper>
+
+## Providing key description
+
+You can read more about providing key descriptions [here](/platform/translation_keys/keys#key-description).
+Tolgee uses the same key description for AI translation as visible in the Translation editor.

platform/projects_and_organizations/languages.mdx

@@ -3,60 +3,33 @@ id: languages
 title: Languages
 sidebar_label: Languages
 ---
+import { ScreenshotWrapper } from "../shared/_ScreenshotWrapper";
+
 
-## Languages settings
 ### Adding new language
-To add a language to the project, simple use the search field to find the language (or to create a custom one). If you want to add that language, simply click `Add`.
+To add a language to the project,
+- Click the `+ Language` button
+- Then start to type in the search field to find the language
+- Select the desired language or click `+ New custom language` to create a custom one.
 
-![Add language](/img/docs/platform/languages_add.png)
+<ScreenshotWrapper
+  alt="Add language"
+  src="/img/docs/platform/languages_add.webp"
+/>
 
 If you want to edit the language details before adding it to the project, click on the pencil icon.
 You can also change the language tag, original name and English name, and flag.
 
-![Add language details](/img/docs/platform/languages_add_details.png)
-
-### Editing languages
-When opening the Languages settings, you can see the list of all languages in the project. You can **change the base language** in the [project settings](project_settings).
-![Languages settings](/img/docs/platform/languages_settings.png)
-
-You can edit the language details by clicking on the cog icon in the language list. You can also change the language tag, original name and English name, and flag.
-And if you wish to delete the language, you can do so by clicking the `Delete language` button.
-
-![Language details](/img/docs/platform/languages_language_details.png)
-
-
-## Machine translation settings
-
-Machine translation (MT) uses external providers to translate base text to currently edited language.
-Number of machine translations that you can use is limited by credits which are shown in language settings. You can **buy more credits** in the [billing settings](organization_settings#billing).
-
-Currently, we support the following machine translation providers:
-
-- Tolgee AI translator based on ChatGPT
-- Google Translate
-- Amazon Translate (AWS)
-- DeepL
-- Microsoft Azure Translator (Azure Cognitive)
-
-You can selectively **enable or disable machine translation suggestions** for each language and each MT provider.
-When you set a "primary" MT provider, it will be displayed first in the suggestions list and will be used for [automatic translation](#automatic-translation) and for [batch machine translations](/platform/translation_keys/batch_operations#available-batch-operations).
-
-Some providers support formality selection (for certain languages), you can adjust that with the formality select.
-
-![Machine translation settings](/img/docs/platform/languages-mt-settings.png)
-
-To enable machine translation when self-hosting, please check out the [configuration](/platform/self_hosting/configuration#machine-translation).
-
-> TIP: You can adjust default settings that will be used for all languages, or you can edit settings for individual languages, which will override the default.
-
-### Automatic translation
-
-Automatic translation is a feature that allows you to translate base text automatically when a new string is added.
-
-You can enable whether Tolgee should automatically translate new strings by looking for **100% translation memory matches** or by using **machine translation** with the selected primary MT provider. You can also enable automatic translation when there are **new keys imported** by the CLI, Import UI or any REST API endpoint importing multiple keys. 
+<ScreenshotWrapper
+  alt="Add language details"
+  src="/img/docs/platform/languages_add_details.webp"
+/>
 
-Auto translation is also triggered when base language value is changed from empty to non-empty. 
+### Editing Languages
+Upon opening the Languages settings, a list of all languages in the project is visible.
+The base language can be **changed** in the [project settings](project_settings).
 
-Translations that were translated automatically (and not edited by humans) are marked by a provider indicator or translation memory indicator. You can clear this indicator by hitting the remove button displayed while hovering the indicator icon. Until you touch the value manually or clear the indicator, the translated value will be automatically updated as the base language translation is updated.
+To edit the language details, click on the cog icon in the language list.
+This allows changes to the language tag, original name, English name, and flag.
 
-![Automatic translation](/img/docs/platform/auto_translation.png)
+To delete a language, click on the `Delete language` button.

platform/projects_and_organizations/machine_translation_settings.mdx

@@ -0,0 +1,47 @@
+---
+id: machine-translation-settings
+title: Machine Translation Settings
+sidebar_label: Machine Translation
+---
+import { ScreenshotWrapper } from "../shared/_ScreenshotWrapper";
+
+Machine translation (MT) uses external providers to translate base text to currently edited language.
+Number of machine translations that you can use is limited by credits which are shown in language settings. You can **buy more credits** in the [billing settings](organization_settings#billing).
+
+Currently, we support the following machine translation providers:
+
+- Tolgee AI translator based on ChatGPT
+- Google Translate
+- Amazon Translate (AWS)
+- DeepL
+- Microsoft Azure Translator (Azure Cognitive)
+
+You can selectively **enable or disable machine translation suggestions** for each language and each MT provider.
+When you set a "primary" MT provider, it will be displayed first in the suggestions list and will be used for [automatic translation](#automatic-translation) and for [batch machine translations](/platform/translation_keys/batch_operations#available-batch-operations).
+
+Some providers support formality selection (for certain languages), you can adjust that with the formality select.
+
+:::info
+Tolgee AI translator uses metadata to provide better results. [Read more here](/platform/translation_process/tolgee_translator).
+:::
+
+<ScreenshotWrapper
+  alt={"Machine translation settings"}
+  src={"/img/docs/platform/languages-mt-settings.webp"}
+/>
+
+To enable machine translation when self-hosting, please check out the [configuration](/platform/self_hosting/configuration#machine-translation).
+
+> TIP: You can adjust default settings that will be used for all languages, or you can edit settings for individual languages, which will override the default.
+
+### Automatic translation
+
+Automatic translation is a feature that allows you to translate base text automatically when a new string is added.
+
+You can enable whether Tolgee should automatically translate new strings by looking for **100% translation memory matches** or by using **machine translation** with the selected primary MT provider. You can also enable automatic translation when there are **new keys imported** by the CLI, Import UI or any REST API endpoint importing multiple keys.
+
+Auto translation is also triggered when base language value is changed from empty to non-empty.
+
+Translations that were translated automatically (and not edited by humans) are marked by a provider indicator or translation memory indicator. You can clear this indicator by hitting the remove button displayed while hovering the indicator icon. Until you touch the value manually or clear the indicator, the translated value will be automatically updated as the base language translation is updated.
+
+![Automatic translation](/img/docs/platform/auto_translation.png)

platform/shared/_ScreenWrapper.css

@@ -5,6 +5,11 @@
   display: inline-grid;
   overflow: hidden;
 }
+.screen-wrapper--container img {
+  max-width: 100%;
+  width: auto;
+  height: auto;
+}
 
 .screen-wrapper--header {
   background: #f8f9f9;

platform/translation_keys/keys.mdx

@@ -3,6 +3,7 @@ id: keys
 title: Keys
 sidebar_label: Keys
 ---
+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.
@@ -27,35 +28,54 @@ To add new translation keys to Tolgee, you have a few options:
 
 To create a new translation key, click the `+ Add` button on the project's Translations view.
 
-![Add key button](/img/docs/platform/add_key_button.png)
+<ScreenshotWrapper
+  alt="Add key button"
+  src="/img/docs/platform/add_key_button.webp"
+/>
 
 When adding a new key, you can specify the following options:
 
 - **Key name**: The name of the key. This name is used to identify the key in the translation files and in the code. The name must be unique within a project.
 - **Namespace**: The namespace of the key. This is an optional field that can be used to structure keys into different "buckets" – namespaces separate translation keys to separate files.
-  It can be useful in large projects, we recommend it for projects with more than ~1000 keys. You can learn more on the [Namespaces](namespaces) page.
+It can be useful in large projects, we recommend it for projects with more than ~1000 keys. You can learn more on the [Namespaces](namespaces) page.
 - **Tags**: Tags can be used to group keys together. You can select multiple tags. You can learn more on the [Tags](tags) page.
 - **Language text(s)**: The text that should be displayed to the user in each language. You can specify the text for one or more languages.
-  You can select which languages to show here by selecting them in the dropdown at the top. If you don't specify the text for a language, the key will be marked as "Untranslated" for that language.
+You can select which languages to show here by selecting them in the dropdown at the top. If you don't specify the text for a language, the key will be marked as "Untranslated" for that language.
 
-![Create key form](/img/docs/platform/create_key_form.png)
+<ScreenshotWrapper
+  alt="Create key form"
+  src="/img/docs/platform/create_key_form.webp"
+/>
 
 ## Naming 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:
 
 1. **Meaningful names**: Translation keys should be named based on the meaning or purpose of the content they represent.
-   For example, a translation key for a button that says `Save` could be named `save_button`.
+For example, a translation key for a button that says `Save` could be named `save_button`.
 2. **Descriptive names**: It's also helpful to use descriptive names that provide additional information about the content, such as the location of the content or its function.
-   For example, a translation key for a header that appears on the homepage could be named `homepage_header`.
+For example, a translation key for a header that appears on the homepage could be named `homepage_header`.
 3. **Consistent naming**: To ensure consistency across translation keys, it's recommended to follow a standard naming convention.
 4. **Short and memorable**: Translation keys should be short and easy to remember.
-   Avoid using long, complicated names that are difficult to type or remember.
+Avoid using long, complicated names that are difficult to type or remember.
 
 Overall, the most important factor is to choose a naming convention that makes sense for your specific project or organization, and to use it consistently throughout the translation process.
 This can help to ensure that translation keys are easy to manage and understand, and that translations are accurate and consistent.
 
 :::tip
 If you want to learn more about naming translation keys, check out our [blog post](/blog/naming-translation-keys) on the topic.
 :::
+
+
+## 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/tolgee_translator) to help it understand the key.
+
+You can see the description in the editor directly under the key name.
+
+<ScreenshotWrapper
+  alt="Key description"
+  src="/img/docs/platform/key_description.webp" />
+
+To modify the description, you can do so in the key editing dialog by clicking the key name or description.