Managing Translations

Translations are the core of LangSyncer. Each translation consists of a key, a group, and values in multiple languages.

Understanding Translations

Translation Structure

Each translation has:

How It Maps to Laravel

In LangSyncer:

Group: messages
Key: welcome
Value (en): Welcome to our application
Value (es): Bienvenido a nuestra aplicacion

In Laravel files:

// resources/lang/en/messages.php
return [
    'welcome' => 'Welcome to our application',
];

// resources/lang/es/messages.php
return [
    'welcome' => 'Bienvenido a nuestra aplicacion',
];

// Usage in code:
__('messages.welcome')

Scopes: Project vs Global

Translations can exist in two scopes:

More on global translations in the Global Translations Library section.

Creating Translations

Step-by-Step

1. Go to Translations
2. Select your project (or switch to Global scope)
3. Click Add Translation
4. Fill in the form:

5. Optionally, use AI Autofill to translate to other languages (see AI Autofill)
6. Click Save

Note: New translations are saved as drafts. They won't be live until you Publish.

Key Naming Best Practices

Use lowercase and dots:

auth.login.button
profile.settings.title
validation.email.required

Be descriptive but concise:

user.greeting          (good)
user_greeting_message  (avoid underscores)

Mirror your app structure:

checkout.cart.empty
checkout.payment.success
checkout.confirmation.title

Using Placeholders

Laravel supports placeholders for dynamic content:

Welcome back, {name}!
You have :count new messages.

The AI translation preserves placeholders automatically.

Editing Translations

Edit a Single Translation

1. Find the translation in the list
2. Click the Edit button to open the edit modal
3. Modify any language value
4. Optionally, use AI Autofill to translate to other languages (see AI Autofill)
5. Click Save

Changes are saved as a draft version until published.

Status Indicators

AI Autofill

Use AI to automatically translate content to all project languages. This feature is available both when creating and editing translations.

How to Use

1. Enter text in your source language (e.g., English)
2. Select the Source Language if needed (defaults to project's base language)
3. Click AI Autofill
4. AI translates to all empty language fields
5. Review and adjust if needed
6. Click Save

AI Translation Features

• Context-Aware: Uses the key name for context
• Placeholder Preservation: Keeps {name}, :count intact
• Format Preservation: Maintains line breaks and punctuation

Quota Consumption

Each AI translation consumes 1 unit from your quota:

• Account-level quota from your subscription tier
• Project-level limits (if configured)

If you hit a limit, you'll see a warning and AI translation will stop.

Selecting Source Language

By default, the source language is your project's base language. To translate from a different language:

1. Use the Source Language dropdown in the edit form
2. Select the language with the text you want to translate from
3. Click AI Autofill

Versioning System

LangSyncer uses a versioning system so you can make multiple edits before publishing.

How It Works

Edit -> Save (Draft) -> Edit Again -> Save (Draft) -> ... -> Publish (Active)

1. Save creates or updates a draft version
2. Draft versions are NOT visible to your applications
3. Publish promotes all drafts to active
4. Applications only see active versions

Benefits

• Batch Edits: Make many changes, publish once
• Review Before Live: Check all changes before deploying
• Efficient CDN Updates: One CDN regeneration per publish, not per edit

Viewing Version History

1. Find the translation
2. Click the History icon
3. See all versions with:
   • Version number
   • Status (Draft/Active/Archived)
   • When published
   • Who published it

Actions available:

• View: See the translation values for that version
• Rollback: Restore a previous version as a new draft (does not affect the current active version until you publish)

Publishing Translations

Publishing makes your draft translations live.

How to Publish

1. Make your edits and save (creates drafts)
2. Click the Publish button (top of translations page)
3. Review the pending changes count
4. Add optional Release Notes (recommended)
5. Click Publish

What Happens When You Publish

1. All draft versions become active
2. Previous active versions are archived
3. CDN files are regenerated (delayed ~30 seconds)
4. Webhooks are dispatched (delayed ~2-3 minutes)
5. A publication record is created

Multi-Project Publishing

If you're a Super Admin or have access to multiple projects:

1. Click Publish without selecting a project
2. See all projects with pending changes
3. Select which projects to publish
4. Click Publish Selected

Each project is published sequentially with progress indicators.

Who Can Publish

Publication Tips

Batch your changes:

• Make multiple edits throughout the day
• Publish once at the end
• Reduces CDN regeneration overhead

Add release notes:

• Document what changed and why
• Helps with troubleshooting later
• Example: "Fixed checkout button translations, added FAQ section"

Global Translations Library

Global translations are shared across all projects in your account.

Use Cases

• Common UI: "Save", "Cancel", "Delete", "Close"
• Standard Messages: "Success!", "Error occurred", "Loading..."
• Form Validation: "Required field", "Invalid email"

Benefits

• No Duplication: Define once, use everywhere
• Consistency: Same terms across all projects
• Easy Updates: Change globally affects all projects

Creating Global Translations

1. Switch to Global scope (button at top of translations page)
2. Click New Translation
3. Fill in group, key, and values
4. Click Save
5. Publish to make available to all projects

Overriding Global Translations

Sometimes a project needs a different value for a global translation.

Example:

• Global: common.submit = "Submit"
• Project A needs: "Send Application"

To Create an Override:

1. Go to Global scope
2. Select the translation(s) you want to override
3. Click Actions > Copy to Project
4. Select the target project
5. Edit the values in the project
6. Save and Publish

How Overrides Work:

• Project translation takes precedence over global
• Global remains unchanged for other projects
• Delete the project translation to revert to global

Promoting to Global

You can promote project translations to global:

1. Select translations (checkboxes)
2. Click Bulk Actions > Promote to Global
3. Handle any conflicts (same group/key already exists globally)
4. Confirm

Bulk Operations

Perform actions on multiple translations at once.

Selecting Translations

• Individual: Click checkbox next to translation
• Current Page: Click "Select All" checkbox in header
• All Matching: Click "Select all X matching" banner

Available Bulk Actions

Bulk Delete

1. Select translations
2. Click Bulk Actions > Delete
3. Confirm deletion

Warning: Deleted translations cannot be recovered.

Bulk Change Group

Move translations to a different group:

1. Select translations
2. Click Bulk Actions > Change Group
3. Enter new group name
4. Click Update

Creates drafts - remember to publish.

Bulk Export

Export selected translations:

1. Select translations
2. Click Bulk Actions > Export
3. Choose format: JSON or CSV
4. Select languages to include
5. Click Export

JSON Format:

{
  "messages.welcome": {
    "en": "Welcome",
    "es": "Bienvenido"
  }
}

CSV Format:

group,key,en,es
messages,welcome,Welcome,Bienvenido

Bulk Copy to Project

Copy translations to another project:

1. Select translations
2. Click Bulk Actions > Copy to Project
3. Select target project
4. Click Copy

By default, "Skip if translation already exists" is checked. Uncheck it to resolve conflicts manually—a modal will let you choose which existing translations to override.

Bulk Promote to Global

Promote project translations to global:

1. Select translations
2. Click Bulk Actions > Promote to Global
3. Click Promote

By default, "Skip if translation already exists" is checked. Uncheck it to resolve conflicts manually.

Filtering and Searching

Search

Type in the search box to filter by:

• Key (partial match)
• Group (partial match)

Filters

Group Filter:

• Select a specific group
• Only shows groups with translations

Status Filter:

• All: Show everything
• Active: Only published translations
• Pending: Only translations with unpublished changes (new or edited)

Sorting

Click column headers to sort by:

• Group
• Key
• Status

Click again to reverse direction.

Best Practices

Organize with Groups

Mirror Laravel's convention:

• auth - Login, register, password reset
• validation - Form validation messages
• pagination - Pagination text
• passwords - Password reset messages

Add your own:

• marketing - Landing page content
• emails - Email templates
• errors - Error messages
• api - API response messages

Workflow Recommendations

1. Developer adds keys with source language values
2. Use AI translation for initial pass
3. Review AI output - especially for marketing/legal content
4. Test in app before publishing
5. Batch publish at end of day/sprint

Security

• Translation values can contain HTML - sanitize when needed
• Placeholders like {name} should use escaped output in templates
• Review AI translations for unexpected content

Troubleshooting

Translation Not Appearing in App

1. Did you Publish? Check for pending badge
2. Has your app synced? Run php artisan translator:sync
3. Is caching enabled? Clear cache: php artisan cache:clear
4. Check group/key spelling (case-sensitive)

AI Translation Not Working

1. Verify you have quota remaining
2. Check if source language has content
3. Review error messages in the toast notification

Publish Button Disabled

• No pending changes to publish
• You don't have publish permissions (need Project Admin role)

Next Steps

• AI Translations - Deep dive into AI features
• Code Scanner - Scan your codebase for translations
• Quota Management - Understand and manage quotas