8. Localization

Klariton localizes the answer layer: BIQs, persona labels and touchpoint content. It does not translate your entire shop.

Current Product State

Translation Management is planned for a later release. The current primary product language is English. This chapter documents the localization model and the intended operating concepts, but the full self-serve Translation Manager, bulk translation workflow and review queue should not be treated as generally available today.

Open Settings -> Glossary to manage terminology that should stay consistent. Translation controls may appear in internal or staged environments, but customer-facing availability depends on release state and plan setup.

Assumption: if your workspace has a custom build with translation controls enabled, the in-app state is the source of truth.

How It Works

Each BIQ has a source language and can have translated variants. The source stays the truth. When the source answer changes, translations are marked stale and can be regenerated.

The planned localization model covers:

BIQ questions and answers,
persona tab labels used in touchpoints,
customer-facing touchpoint labels where a multi-locale touchpoint supports them.

Klariton does not automatically translate every Shopify product page, policy page, blog post or checkout text. Those stay in your shop or CMS.

Source Locale, Target Locales And Fallbacks

The source locale comes from the organization locale. Target locales are the languages an organization intends to serve. In the planned Translation Management workflow, Klariton uses target locales for translation jobs, translation coverage, re-sync and multi-locale touchpoints.

Supported pilot target locales in the current app are:

en, fr, es, it, nl, pl, pt, sv, da, fi, cs, el, hu, ro, sk, sl, et, lt, lv.

If a requested touchpoint locale has no current translation, Klariton can fall back to the source content where the integration supports fallback behavior.

Translation Engines And Data Protection COMING SOON

Klariton supports:

DeepL: recommended default, EU-hosted, strong for product and marketing text.
OpenAI: opt-in alternative that may process content outside the EU depending on your setup and DPA.

OpenAI would require explicit data-protection confirmation before activation. Use DeepL when you need the default EU-focused setup.

API-Key Strategy COMING SOON

For DeepL, Klariton supports two key strategies:

Klariton-managed: the default shared setup with a monthly translation budget cap.
Bring your own key: stores your DeepL key encrypted and uses it for your organization.

In the planned model, only organization owners can change key strategy, save a BYO key, clear a BYO key or change the monthly cap. Owners and admins can change the translation engine, target locales and x-default locale where enabled.

Monthly Budget Cap COMING SOON

Klariton-managed translation is planned to have a monthly cap. The future Translations tab should show:

used amount this month,
configured monthly limit,
reset date,
cap-exceeded warning when new jobs are blocked.

Before bulk translation starts, Klariton should show a cost estimate and ask for confirmation. This protects teams from starting large translation jobs accidentally.

Glossary LIVE

The glossary keeps brand names, product names, model codes and specialist terms consistent.

Sources:

Auto-built glossary from product data.
Manual terms.
CSV import/export.
Translation overrides per language.

Build the glossary before large translation waves.

Glossary terms can be marked as do not translate. These terms are injected into DeepL glossaries and OpenAI prompts so names, SKUs, product families and specialist terms stay stable.

Use the automatic glossary for Shopify-derived product terms. Use manual or CSV terms for brand language, claims, model numbers, spelling variants and terms that must stay verbatim.

Translation Management COMING SOON

The full Translation Manager is planned for a later release. Do not rely on it as a current self-serve workflow unless it is explicitly enabled in your workspace.

The planned manager will filter BIQs by:

target language,
status: missing, current, stale or review,
search text in the BIQ question.

The intended workflow is:

Choose a target language.
Filter for Not translated or Outdated.
Select all matching results.
Check the cost estimate.
Confirm the job.
Review items that enter the review queue.

This is designed for large catalogs. Klariton should filter server-side and load results incrementally, so you do not need to inspect a full BIQ-by-language matrix manually.

Bulk Re-Sync COMING SOON

Bulk Re-Sync is part of the planned Translation Management workflow.

Bulk Re-Sync supports two source filters:

All published BIQs: useful for the first translation wave.
Stale only: useful after source edits, SafeGuard corrections or content refreshes.

The intended flow is estimate first, confirm second. If the selection would create many jobs, Klariton fans the work out into translation jobs and sub-jobs per target locale.

Review And Approval COMING SOON

Some translations go live immediately. Others enter the review queue first. OpenAI translations and overridden review configurations can require manual approval before publication.

In the review queue, you see the source BIQ on the left and the translated BIQ on the right. You can:

edit the translated question,
edit the translated answer,
publish the translation,
reject it so the locale falls back to missing and can be translated again.

Use review for legally sensitive claims, ingredient explanations, product safety wording, medical-adjacent wording, compliance-sensitive brand promises and any locale where your team wants a human check.

Stale Detection COMING SOON

When a source BIQ changes, translations become stale. In the planned workflow, use review and re-sync flows to update them.

Stale translations are not a bug. They are a work queue showing what needs attention.

Translations can become stale after:

manual BIQ edits,
SafeGuard corrections,
drift rewrites,
product or material refreshes that change the source answer,
source hash backfills or source-locale corrections.

Future dashboard and curation views can show translation coverage for a touchpoint, including how many items are current, missing, stale or waiting for review per locale.

Persona Labels COMING SOON

When translation jobs or re-sync flows run, Klariton also translates persona tab labels into the target locales where possible. This keeps touchpoint navigation aligned with translated BIQs.

Multi-Locale Touchpoints

Multi-locale touchpoints let one touchpoint serve multiple language variants. Where not available in a plan, create separate language touchpoints or limit public languages.

Use the locale parameter in embed code or widget requests to request a language variant. For Shopify, pass the storefront locale when possible.

Example:

<klariton-faq
  org="your-org"
  touchpoint="product-faq"
  locale="{{ request.locale.iso_code | default: 'en' }}"
></klariton-faq>

hreflang And x-default COMING SOON

Klariton can expose language relationships for crawler discovery. Set x-default to the strongest fallback language when the translation and sitemap controls are enabled.

The planned path is Settings -> Translations -> Sitemap default language. If unset, Klariton falls back to the source locale.

Troubleshooting

Translations Are Missing

Check:

the target locale is enabled,
the BIQ is published,
the locale is included in the current touchpoint or embed request,
the monthly cap has not been reached,
the translation job did not fail,
the glossary or source text does not contain malformed data.

Translations Are Outdated

This means the source BIQ changed after translation. When Translation Management is available, run the manager or Bulk Re-Sync for the affected locale.

Review Queue Does Not Clear

Publish or reject each pending item. Rejected items become missing and can be translated again.

OpenAI Cannot Be Enabled

Only owners can confirm the data-protection notice. Confirm that the user has owner permissions and that your organization has the required DPA setup.

Costs Are Blocked

When Translation Management is available, check the monthly cap and current usage. Owners can increase the cap or switch to BYO DeepL key where supported.

Best Practices

Keep source BIQs high quality before translating.
Build the glossary before the first large translation wave.
Keep source locale and target locales intentional; avoid enabling locales you do not plan to review.
When Translation Management is released, use filters instead of translating everything blindly.
Review sensitive translations side by side before publishing.
Re-sync after SafeGuard corrections.
Track translation budget in Settings.
Test every public locale in the touchpoint before publishing it broadly.