diff --git a/platform/translation_process/qa_checks.mdx b/platform/translation_process/qa_checks.mdx new file mode 100644 index 00000000..5b64a7a6 --- /dev/null +++ b/platform/translation_process/qa_checks.mdx @@ -0,0 +1,192 @@ +--- +id: qa_checks +title: Translation QA Checks +sidebar_label: QA Checks +image: /img/og-images/platform.png +description: Automatically detect translation quality issues like missing placeholders, inconsistent punctuation, broken placeholder syntax, spelling and grammar errors with Tolgee's built-in localization QA checks. +--- + +import { ScreenshotWrapper } from '../shared/_ScreenshotWrapper'; +import { ScreenRecording } from '../shared/_ScreenRecording'; + +When managing translations across many languages, it's easy for localization errors to slip through. A translator might accidentally remove a placeholder, break [placeholder syntax](/platform/translation_process/icu_message_format), add extra spaces, or miss punctuation. These translation quality issues are hard to spot manually, especially at scale, and can lead to broken UI, missing data, or confusing user experiences. + +QA Checks solve this by automatically validating your translations and flagging potential issues such as missing placeholders, broken placeholder syntax, inconsistent punctuation, spelling and grammar errors, and more. Issues are detected **in real time** as you type and also run in the background when translations are saved or modified in bulk. + +{/* TODO: Screenshot - overview of QA checks panel in the translation editor showing a few issues */} + +:::info Feature availability +QA Checks are available in advanced plans. [Upgrade your plan](https://tolgee.io/pricing) to use this feature. + +If you use the self-hosted version, you must [set up the license](https://tolgee.io/pricing/self-hosted) to use this feature. +::: + +## Enabling QA Checks + +If you would like to start using QA checks, you have to enable them first. To enable QA checks + +1. Go to `Project settings` +2. Find the `QA Checks` section +3. Toggle QA Checks on + + + +Once enabled, Tolgee will automatically run checks on all translations in the project. You'll see a progress indicator while the initial check completes. + +## Available Check Types + +Tolgee provides check types organized into two categories: **general checks** that catch common translation issues, and **syntax checks** that validate the structure of the translation itself. + +### General Checks + +These checks catch common translation issues such as formatting inconsistencies, missing content, and spelling or grammar errors + +| Check | Description | +|-------|-------------| +| **Empty translation** | Detects blank or whitespace-only translations (off by default) | +| **Spaces mismatch** | Leading/trailing space differences, doubled spaces, non-breaking spaces | +| **Unmatched new lines** | Missing or extra line breaks compared to the base translation | +| **Character case mismatch** | Capitalization differences (e.g., first letter case) | +| **Missing numbers** | Numeric values present in the base but missing in the translation | +| **Punctuation mismatch** | Missing, extra, or replaced punctuation marks | +| **Brackets mismatch** | Missing or extra brackets compared to the base | +| **Brackets unbalanced** | Unclosed or unopened brackets within the translation | +| **Special character mismatch** | Missing or extra special characters (off by default) | +| **Different URLs** | URLs that are missing, extra, or different from the base | +| **Key length limit** | Translation exceeds the key's configured [character limit](/platform/translation_keys/keys#character-limit) | +| **Spelling** | Spelling errors (off by default) | +| **Grammar** | Grammar errors (off by default) | +| **Repeated words** | Consecutive repeated words (e.g., "the the") | +| **Unresolved comments** | Translation has unresolved [comments](/platform/translation_process/comments) that should be addressed | + +### Syntax Checks + +These checks validate the structure and syntax of the translation itself + +| Check | Description | +|-------|-------------| +| **Inconsistent placeholders** | Variable placeholders (e.g., `{userName}`) missing or extra compared to the base | +| **Inconsistent HTML** | HTML tags missing or extra compared to the base | +| **HTML syntax** | Unclosed or unopened HTML tags | +| **ICU syntax** | Invalid [message format](/platform/translation_process/icu_message_format) (select, plural, choice expressions) | + +## Viewing QA Issues + +### In the Translation Editor + +To help translators catch issues as they work, QA checks are shown directly in the translation editor. When you open a translation for editing, the QA checks panel appears below the text field. Each issue shows + +- The **check type** (e.g., "Spaces mismatch") +- A **description** of what was detected +- A **suggested replacement** when available, with highlighted differences + + + +Issues are updated **in real time** as you type, so you get immediate feedback on your changes. + +### Inline Highlights + +Problematic text spans are highlighted directly in the translation editor. Hovering over a highlight shows the issue details and a suggested fix. + + + +### QA Badge + +A QA badge appears next to translations in the translations list view when there are open issues or checks are still running + +- **Badge with count** - number of open issues +- **Spinner** - checks are still running (e.g., after an [import](/platform/projects_and_organizations/import) or settings change) + +When all issues are resolved, the badge disappears. + + + +## Fixing Issues + +### One-Click Corrections + +When a check provides a suggested replacement, you can apply it with a single click on the `Correct` button. The fix is applied directly to the translation text. + + + +### Ignoring Issues + +Sometimes a flagged issue is intentional or a false positive. For example, you might deliberately omit a placeholder in a specific language, or a grammar check might not understand a domain-specific term. In these cases, you can `Ignore` the issue. Ignored issues won't count toward the issue total and won't appear as warnings. + +To ignore an issue, click the `Ignore` button next to it in the QA panel. You can also `Unignore` it later if needed. + + + +## Configuring Check Severity + +You can customize which checks are active and their severity at both the **project level** and the **language level**. + +### Project-Level Settings + +To configure QA checks for your entire project + +1. Go to `Project settings` > `QA Checks` +2. For each check type, set the severity + - `Warning` - the check is active and issues are reported + - `Off` - the check is disabled + +*Currently, only two severity levels are supported: `Warning` and `Off`. More severity levels may be added in the future.* + +Most checks default to `Warning`. The exceptions are **Empty translation**, **Special character mismatch**, **Spelling**, and **Grammar**, which default to `Off`. + + + +### Language-Level Overrides + +Some checks may not be relevant for all languages. For example, character case checks don't apply to languages without case distinctions, and certain punctuation rules differ across writing systems. Language-level overrides let you fine-tune settings for these cases. + +To configure overrides for a specific language + +1. Go to `Project settings` > `QA Checks` +2. Click on the `Language overrides` section +3. Select a language and adjust the settings + + + +Language-level settings always take precedence over project-level settings. Changing project settings does not affect languages that already have overrides. You can reset a language back to project defaults at any time. + +## When QA Checks Run + +QA checks run in real time as you type in the translation editor, so you get immediate feedback without saving first. When you save a translation, all enabled checks run again and results are persisted. This also applies to [imported](/platform/projects_and_organizations/import) translations. The QA badge and issue counts are updated accordingly. + +The system is designed to handle all rechecking automatically, so you should never need to trigger a manual recheck under normal circumstances. However, as a last resort, you can manually trigger a full QA recheck for all translations in a project from the translations view using [batch operations](/platform/translation_keys/batch_operations). + + + +Checks are also automatically re-run when the base language translation changes, a language tag is changed, or [branches are merged](/platform/branching/merging_branches). + +### Plural Translations + +For translations that use plural forms, QA checks run separately on each plural variant. Issues are reported per variant, so you can see exactly which form has the problem. diff --git a/sidebarPlatform.js b/sidebarPlatform.js index 6a3e820b..eb9e1e29 100644 --- a/sidebarPlatform.js +++ b/sidebarPlatform.js @@ -66,6 +66,7 @@ module.exports = { 'translation_process/labels', 'translation_process/icu_message_format', 'translation_process/tolgee_universal_icu_placeholders', + 'translation_process/qa_checks', 'translation_process/notifications', ], }, diff --git a/static/img/docs/platform/qa-checks/correct.webm b/static/img/docs/platform/qa-checks/correct.webm new file mode 100644 index 00000000..e5c92883 Binary files /dev/null and b/static/img/docs/platform/qa-checks/correct.webm differ diff --git a/static/img/docs/platform/qa-checks/enable.webm b/static/img/docs/platform/qa-checks/enable.webm new file mode 100644 index 00000000..62519590 Binary files /dev/null and b/static/img/docs/platform/qa-checks/enable.webm differ diff --git a/static/img/docs/platform/qa-checks/ignoer.webm b/static/img/docs/platform/qa-checks/ignoer.webm new file mode 100644 index 00000000..88882014 Binary files /dev/null and b/static/img/docs/platform/qa-checks/ignoer.webm differ diff --git a/static/img/docs/platform/qa-checks/inline_highlights.webm b/static/img/docs/platform/qa-checks/inline_highlights.webm new file mode 100644 index 00000000..c47cf580 Binary files /dev/null and b/static/img/docs/platform/qa-checks/inline_highlights.webm differ diff --git a/static/img/docs/platform/qa-checks/language_level_qa_settings.webm b/static/img/docs/platform/qa-checks/language_level_qa_settings.webm new file mode 100644 index 00000000..b41f8aa9 Binary files /dev/null and b/static/img/docs/platform/qa-checks/language_level_qa_settings.webm differ diff --git a/static/img/docs/platform/qa-checks/project_level_qa_settings.webm b/static/img/docs/platform/qa-checks/project_level_qa_settings.webm new file mode 100644 index 00000000..1f43a347 Binary files /dev/null and b/static/img/docs/platform/qa-checks/project_level_qa_settings.webm differ diff --git a/static/img/docs/platform/qa-checks/recheck_batch.webm b/static/img/docs/platform/qa-checks/recheck_batch.webm new file mode 100644 index 00000000..718faf7f Binary files /dev/null and b/static/img/docs/platform/qa-checks/recheck_batch.webm differ diff --git a/static/img/docs/platform/qa-checks/spinner.webm b/static/img/docs/platform/qa-checks/spinner.webm new file mode 100644 index 00000000..dfa1050f Binary files /dev/null and b/static/img/docs/platform/qa-checks/spinner.webm differ diff --git a/static/img/docs/platform/qa-checks/translations_view.webm b/static/img/docs/platform/qa-checks/translations_view.webm new file mode 100644 index 00000000..13c8e787 Binary files /dev/null and b/static/img/docs/platform/qa-checks/translations_view.webm differ