Dashboard guide

AI Translation

langctl uses DeepL to fill in missing translations from your default language. AI translations are held back from your app until someone reviews them.

Overview

AI translation in langctl provides:

• Suggest: Translate one language of one key in its detail panel
• Translate missing: Fill every empty translation for many keys and languages at once
• Placeholder protection: {{parameters}} are kept intact
• Project AI settings: context, a do-not-translate list, a glossary and tone per language, applied to every AI translation
• Key descriptions as context: each key’s description tells DeepL what a short string means
• Review before shipping: AI translations are left out of exports and langctl pull until they’re approved or edited

AI translation is managed by langctl - there’s no provider key to configure. It’s available to members, admins and owners (not viewers), and your email address must be verified.

Project AI Settings

Short UI strings are ambiguous: on its own, “Book” is a thing you read, “Open” is a command and “Credit” can mean praise. Give DeepL the context it needs in Project settings → AI translation. Members can see these settings; owners and admins can change them (API keys need the projects:write scope).

Key descriptions

A key’s description is sent to DeepL as context too, after the project context, so describe where a short string appears: “Button that makes a booking”, “Badge: the business is open right now”, “Transaction type: money coming in”. Set descriptions in the key’s detail panel, or in bulk with an import file that carries them (rich values { "value": "…", "description": "…" }); an import sets the description of existing keys whenever it differs from the stored one.

How the glossary is applied

• Where DeepL supports glossaries for the language pair (for example English → German, French, Spanish, Japanese or Portuguese), langctl creates a DeepL glossary from your entries and uses it. It’s rebuilt automatically when you change the glossary.
• For other pairs (for example English → Hindi), langctl puts your preferred translation in place of the source term before the text goes to DeepL and tells DeepL to leave it alone, so it comes back exactly as you wrote it. This is the same mechanism as Do not translate, so the rest of the sentence is translated around the term. Add each form you use (booking, Booking, bookings): matching is case-sensitive and whole-word.

Translating a Single Key

1. On Translations, click the key to open its detail panel
2. Next to an empty language, click Suggest
3. The AI translation of the default-language text appears in the field
4. Edit it if needed, then save the key

Translating Missing Translations in Bulk

1. On Translations, either:
   • click Translate missing in the toolbar to translate the keys in the current view (use search and filters to narrow it down), or
   • select keys with the checkboxes and click Translate missing in the bulk bar
2. In the dialog, check the source language and choose the target languages
3. The dialog shows how many translations will be created and how much of this month’s allowance is left
4. Click Translate and keep the page open until it finishes

Bulk translation only fills empty translations - existing translations are never overwritten, including ones a teammate fills in while it runs. The server translates and saves up to 100 keys per request, applying the project’s AI settings and key descriptions. When it’s done you’ll see how many translations were saved and how many DeepL couldn’t translate (those stay empty for a person to fill in).

Reviewing AI Translations

How review state is set

langctl remembers the exact text the AI produced. As soon as the stored text differs from it - edited in the dashboard, pushed from the CLI, imported - it counts as human text and no longer needs review. Approving keeps the AI text and marks it reviewed.

Every AI translation starts as needing review:

• It shows an AI · review badge in the translations list
• It’s left out of exports and langctl pull - your app falls back to the default language for that string until it’s reviewed
• A notice on the Translations page shows how many AI translations need review, with Show them (applies the Needs review filter) and Approve all
• The Languages page shows how many translations each language has waiting for review

To review:

1. Filter by Needs review
2. Open a key and read each AI translation
3. Edit it if needed - editing a translation counts as reviewing it
4. Or click Approve next to the language to accept it as is

To approve many at once, select keys and click Approve AI in the bulk bar, or use Approve all in the notice.

Review state is separate from publishing: a key still needs to be published to be exported, and its AI translations need to be approved (or edited) as well.

If you need unreviewed AI translations in a file anyway - for testing, say - the Export page can include them.

Usage and Quota

Checking Your Quota

• Plan & Billing - AI translations used this month and when the allowance resets
• Settings - AI translations this month
• The Translate missing dialog - what’s left before you start

What Counts as a Translation?

Each key translated into one language counts as one AI translation:

Translating 1 key to 3 languages = 3 translations
Translating 10 keys to 2 languages = 20 translations

Each plan also includes a monthly character allowance sized for typical UI strings (roughly 100 characters per translation), so translating very long texts can use it up sooner.

When You Run Out

When the monthly allowance is used up:

• AI translation is unavailable until it resets; everything else (editing, publishing, pulling, exporting) keeps working
• The allowance resets at the start of each calendar month, independent of when you signed up
• Unused translations don’t roll over
• See Plan & Billing for plans with a higher allowance

Best Practices

Prepare Your Source Content

Write clear source translations:

✅ "Enter your email address to continue"
❌ "Email here pls"

Use consistent terminology:

✅ Always use "user" (not switching between user/member/person)

Module-by-Module Translation

Translate one module at a time:

1. Filter by module, then click Translate missing
2. Review and approve before moving on
3. Small batches are easier to review and keep related keys consistent

Quality Check Process

1. Translate: Use AI for initial translations
2. Review: Check AI output for accuracy, then edit or approve it
3. Publish: Mark keys as ready for production
4. Test: Pull the translations and check them in your app

Language-Specific Considerations

Right-to-Left Languages

Arabic and Hebrew require special attention:

• Check text direction in your app
• Test UI layout with RTL text
• Review punctuation placement

Chinese and Japanese

• Simplified vs Traditional Chinese
• Text length differs from English
• Font and rendering considerations

European Languages

• Formal vs informal (tu/vous, tú/usted) - set the Tone per language in Project settings
• Gender agreement
• Regional variations (es-ES vs es-MX)

Troubleshooting

AI Translation Failed or Unavailable

Common causes:

• Quota used up: Check Plan & Billing
• Empty source: The default-language translation of the key is empty
• Email not verified: Verify your email address first
• Unsupported language pair: DeepL doesn’t support every language; the error names the pair
• Viewer role: Viewers can’t use AI translation

Parameters Not Preserved

Source: "Welcome, {{username}}!"
AI Output: "¡Bienvenido, username!"  ❌
Expected: "¡Bienvenido, {{username}}!"  ✅

langctl protects placeholders (and do-not-translate terms) before sending text to DeepL, so this should be rare. If it happens, edit the translation to restore the placeholder and let us know at support@langctl.com.

From the CLI

Next Steps

• Translation Management - Learn more about managing translations
• Publishing Workflow - Understand draft vs published
• Export Translations - Export your translations
• Subscription & Usage - Plans and AI allowances