Translation Management

Translation keys are the core of your project. Each key represents a piece of translatable content with values in multiple languages.

Understanding Translation Keys

Key Structure

Each translation key in LangCTL has:

• Key Name: Unique identifier (e.g., home.welcome, auth.login.title)
• Translations: Values for each language
• Module: Optional grouping (e.g., “auth”, “dashboard”)
• Description: Optional context for translators
• Published: Boolean flag indicating if key is ready for export
• Created/Updated: Timestamps and user tracking

Translation Key Structure

Each translation key stores values for all languages together:

{
"key": "home.welcome",
"translations": {
  "en": "Welcome to our app!",
  "es": "¡Bienvenido a nuestra aplicación!",
  "fr": "Bienvenue dans notre application!"
},
"module": "home",
"description": "Main welcome message",
"published": true
}

Creating Translation Keys

From the Dashboard

1. Navigate to Translations section

2. Select your project

3. Click “New Translation Key”

4. Fill in the form:

   • Key: Unique identifier (e.g., home.welcome)
   • Module: Optional grouping (e.g., “home”)
   • Description: Context for translators
   • Translations: Add values for each language

5. Choose “Save as Draft” or “Publish”

[IMAGE: create-translation-key.png - Screenshot of the create translation key form]

Key Naming Conventions

Use dot notation for hierarchical organization:

✅ Good:

auth.login.title
auth.login.subtitle
auth.login.button
dashboard.welcome.title
dashboard.stats.users

❌ Bad:

AuthLoginTitle
login_title
titleLogin

Module Assignment

Assign keys to modules during creation:

• Type module name (auto-complete shows existing modules)
• Create new modules by typing a new name
• Leave empty for keys without module grouping

The project’s modules list updates automatically when you add, modify, or delete translation keys.

Editing Translations

Inline Editing

From the translations list:

1. Click on any translation value
2. Edit the text directly
3. Press Enter to save or Esc to cancel

[IMAGE: inline-editing.png - Screenshot showing inline translation editing]

Bulk Editing

Edit multiple translations at once:

1. Select keys using checkboxes
2. Click “Bulk Edit”
3. Choose action:
   • Update module
   • Publish/unpublish
   • Add translations for a language
   • Delete keys

Translation Editor

For detailed editing, use the full editor:

1. Click on a key to open the detail view
2. See all languages in one view
3. Edit individual language values
4. Add description and context
5. Update module assignment
6. Toggle publish status

[IMAGE: translation-editor.png - Screenshot of the full translation editor interface]

Parameter Syntax

Use {{parameter}} syntax for variables:

en: "Welcome, {{username}}!"
es: "¡Bienvenido, {{username}}!"
fr: "Bienvenue, {{username}}!"

en: "You have {{count}} new messages"
es: "Tienes {{count}} mensajes nuevos"
fr: "Vous avez {{count}} nouveaux messages"

Filter translation keys by:

• Module: Show keys from specific modules
• Language Completion: Keys missing translations for specific languages
• Published Status: Draft or published keys
• Recently Updated: Sort by modification date
• Created By: Filter by author

[IMAGE: translation-filters.png - Screenshot of filter sidebar]

The search bar supports:

home.welcome

"Welcome"

missing:es

module:auth

published:false

module:auth AND missing:es

Translation Status

Draft vs Published

Draft Keys:

• Not included in exports by default
• Visible in dashboard with “Draft” badge
• Can be edited freely
• Useful for work-in-progress translations

Published Keys:

• Ready for export and production use
• Included in CLI exports
• Should be complete and reviewed
• Changes trigger version history

Bulk Publishing

You can publish multiple keys at once from the translations list:

1. Select keys using checkboxes
2. Click “Bulk Actions” dropdown
3. Select “Publish Selected”
4. Confirm the action

All selected keys will be marked as published and available for export.

Translation Completeness

Completion Indicators

Visual indicators show translation status:

• ✅ Complete: All languages have translations
• ⚠️ Partial: Some languages missing
• ❌ Empty: No translations yet

[IMAGE: completion-indicators.png - Screenshot showing translation completion badges]

Language-Specific Progress

View progress for each language:

home.welcome
  ✓ en: "Welcome!"
  ✓ es: "¡Bienvenido!"
  ✗ fr: (missing)
  ✗ de: (missing)

Finding Missing Translations

Use the “Missing Translations” filter:

1. Select “Filter” dropdown
2. Choose “Missing Translations”
3. Select target language
4. See all keys without that language

Version History

Every translation change is automatically tracked:

Viewing History

1. Open a translation key
2. Click “View History” tab
3. See all changes with:
   • Timestamp
   • User who made the change
   • Before/after values
   • Languages affected

[IMAGE: translation-history.png - Screenshot of version history view]

History Storage

LangCTL automatically creates a new history record whenever a translation is modified. Each record stores:

• Complete snapshot of all translations at that moment
• Timestamp of the change
• User who made the change
• Languages that were affected

Learn more about version history ->

Deleting Translations

Soft Deletes

Translations use soft deletion with deleted_at timestamp:

• Deleted keys are hidden but not removed from database
• Maintains audit trail and version history
• Can be recovered if needed

Permanent Deletion

Organization owners can permanently delete:

1. Select deleted keys
2. Click “Permanently Delete”
3. Confirm action

Import and Export

Quick Export

Export translations directly from the list:

1. Select keys to export (or select all)
2. Click “Export Selected”
3. Choose language and format
4. Download file

Quick Import

Import translations from the list:

1. Click “Import” button
2. Select file
3. Choose import options
4. Review conflicts
5. Confirm import

Learn more about import/export -> and ->

Collaboration Features

Comments (Coming Soon)

Leave comments on translation keys:

• Ask questions about context
• Request review from team members
• Discuss translation choices
• Get @mentioned notifications

Review Workflow (Coming Soon)

Request reviews before publishing:

• Assign reviewers to keys
• Approve/reject translations
• Track review status
• Require approvals for publishing

Best Practices

Writing Translation Keys

Use descriptive key names:

✅ user.profile.edit.save_button
❌ btn1

Group related keys with modules:

auth/login.*
auth/signup.*
auth/forgot_password.*

Keep key names consistent:

✅ *.button_text  (consistent suffix)
❌ *_btn, *.button, *.btn_text (inconsistent)

Use consistent punctuation:

✅ "Welcome!" (all languages end with !)
❌ "Welcome!" (en), "Bienvenido" (es - missing !)

Respect parameter names:

✅ "Hello, {{username}}!"
❌ "Hello, {{name}}!"  (inconsistent parameter)

Provide context in descriptions:

Description: "Shown after successful login on home page"

Module Organization

Use consistent naming:

✅ auth, dashboard, settings
❌ Auth, DASHBOARD, settings_page

Keep modules focused:

✅ 5-10 modules with clear purposes
❌ 50+ modules with overlapping content

Keyboard Shortcuts

Speed up translation work:

Troubleshooting

Key Already Exists

Error: “Translation key already exists”

• Key names must be unique within a project
• Check if key exists (might be deleted)
• Use a different key name

Can’t Edit Translation

• Verify you have Member role or higher
• Check if project is archived
• Ensure you’re in the correct organization

Missing Translation Not Showing

• Verify language is added to project
• Check filter settings
• Refresh the page

Changes Not Saving

• Check internet connection
• Verify you have edit permissions
• Look for error messages in UI
• Try refreshing and editing again

Next Steps

• AI Translation - Translate keys automatically
• Module Organization - Organize keys effectively
• Publishing Workflow - Manage draft/published lifecycle
• Export Translations - Generate files for your app