Managing Projects

Projects are the foundation of LangSyncer. Each project represents a separate application or website with its own translations, API key, languages, and team members.

Why Use Projects?

• Isolation: Keep translations for different apps completely separate
• Security: Each project has its own API key with independent rate limits
• Quota Control: Set AI translation limits per project
• Team Access: Assign different team members to different projects
• Multi-language: Configure which languages each project supports

Creating a Project

Requirements

Before creating a project, ensure:

• You have the Project Admin role (or are a System Admin)
• Your account hasn't reached its project limit (based on subscription tier)

Step-by-Step

1. Navigate to Translator > Projects in the sidebar
2. Click New Project
3. Fill in the project details:

4. Click Save

What Happens When You Create a Project

The system automatically:

• Generates a unique API key in format lh_proj_{project-id}_{secret}
• Associates the project with your account
• Enables the selected languages
• Sets up CDN distribution paths (if your tier includes CDN)

Note: Your subscription tier determines how many projects you can create. If you've reached your limit, you'll see an alert and the "New Project" button will be disabled.

API Key Management

Each project has a unique API key used to authenticate requests from your application.

Viewing Your API Key

1. Open the project's Actions modal
2. Click the eye icon to reveal the full key
3. Click Copy to copy to clipboard

The API key format is: lh_proj_{project-uuid}_{encoded-secret}

Enabling/Disabling the API Key

You can temporarily disable API access without regenerating your key:

To Disable:

1. Go to API Key settings
2. Click Disable API Key
3. Confirm the action

When disabled:

• CDN access is blocked
• Your applications cannot sync translations

To Re-enable:

1. Click Enable API Key
2. Access is immediately restored

Use Case: Disable your API key temporarily during maintenance or security incidents without losing your key configuration.

Regenerating API Keys

Regenerate your API key if:

• The key has been compromised
• You need to rotate keys for security compliance

To Regenerate:

1. Go to API Key settings
2. Click Regenerate API Key
3. Confirm the action

What Happens:

• A new key is generated immediately
• The old key stops working instantly
• All team members are notified
• You must update your applications with the new key

Warning: After regenerating, update the API key in all your applications immediately. The old key will no longer work.

CDN Access

If your tier includes CDN distribution:

1. Open the project's Actions modal and go to the API Key & CDN tab
2. Find the CDN URL callout (highlighted in amber)
3. Click Copy to copy the full CLI_TRANSLATOR_CDN_URL=... line
4. Add this to your Laravel application's .env file
5. Click Regenerate CDN to manually refresh cached translation files

Required Configuration:

Your Laravel application needs both variables in .env:

CLI_TRANSLATOR_API_KEY=lh_proj_...
CLI_TRANSLATOR_CDN_URL=https://cdn.langsyncer.com

The CDN URL is the base URL where translation files are hosted. Your API key determines the path within the CDN (/{api_key}/manifest.json, /{api_key}/{locale}.json).

Webhooks

Configure webhooks to notify your application when translations change.

Available Events:

• Translations Published - Triggered when you publish translations (required for Live mode to work)
• Single Translation Updated - Triggered when a single translation is modified
• Single Translation Deleted - Triggered when a translation is deleted
• Bulk Translations Updated - Triggered when multiple translations are updated at once
• Project Languages Changed - Triggered when project languages are added or removed

To Create a Webhook:

1. Open the project's Actions modal
2. Go to the Webhooks tab
3. Click Add Webhook
4. Enter the webhook URL (must be HTTPS)
5. Select the events you want to receive
6. Click Create

Each webhook receives a secret key that the translator-client package uses automatically to verify requests.

Managing Webhooks:

• Enable/Disable: Toggle webhook without deleting it
• View Logs: See delivery history and response codes
• View Secret: Reveal the secret key for signature verification
• Delete: Remove the webhook permanently

Managing Team Members

Projects support two types of access:

Project Admins (Account-Level)

• Automatically have access to all projects in their account
• Cannot be removed from individual projects
• Can manage settings, API keys, and team members
• Displayed with a "Project Admin" badge

Collaborators (Project-Level)

• Must be explicitly added to each project
• Cannot edit or delete projects
• Cannot access API keys
• Can be added or removed at any time

Adding Collaborators

1. Go to the project's Team tab
2. Select a user from the dropdown (shows account users with Project Collaborator role)
3. Click Add
4. The user receives a notification and gains immediate access

Removing Collaborators

1. Go to the project's Team tab
2. Find the collaborator you want to remove
3. Click Remove
4. The user is notified and immediately loses access

Note: You cannot remove Project Admins from individual projects - they have account-level access.

Permission Matrix

Project Languages

Configure which languages are available for translations in your project.

Adding Languages

When creating or editing a project:

1. Select the languages you need from the Languages list
2. Choose your Base Language (the source language you develop in)
3. Click Save

Your project can support any combination of the 30+ available languages.

Base Language

• This is your source/development language
• Cannot be disabled while set as base language
• Translation progress is measured against this language

Language Requirements

• You must select at least one language
• The base language must be one of the selected languages
• Removing a language doesn't delete existing translations (they're preserved but not exported)

Project Quota (AI Translation Limit)

Each project can have an optional AI translation quota to control costs.

How Quotas Work

1. Account Quota: Your subscription tier provides a monthly AI translation quota
2. Project Limit: Optionally set a cap per project to distribute quota
3. Quota Packs: Purchase additional quota that applies account-wide

Setting a Project Limit

When creating or editing a project:

1. Find the AI Quota field
2. Enter a number (or 0 for unlimited within account quota)
3. Click Save

Example:

• Account has 10,000 monthly AI translations
• Project A limit: 5,000
• Project B limit: 3,000
• Project C limit: 0 (uses remaining account quota)

Note: Only Project Admins can edit quota settings.

Quota Validation

The system prevents over-allocation:

• Project limit cannot exceed available account quota
• Sum of all project limits cannot exceed account total
• When quota is exhausted, AI translation is disabled for that project

Import/Export

Transfer translations between LangSyncer and your Laravel application.

Importing Translation Files

1. Go to the project's Actions modal
2. In the Import section:
   • Drag and drop files or click to browse
   • Supported formats: .php (Laravel lang files) and .json
3. Select the language these translations belong to (from the project's configured languages)
4. Click Import Translations

What Happens:

• Files are validated for syntax errors
• JSON files are converted to PHP format internally
• New keys are created, existing keys are updated
• Import log is created

Exporting Translation Files

1. Go to the project's Actions modal
2. In the Export section:
   • Choose format: PHP, JSON, or Both
3. Click Export to Files
4. Download links appear in the Recent Exports section

Export Formats:

• PHP: Standard Laravel resources/lang/{locale}/*.php format
• JSON: Single {locale}.json file per language
• Both: Generates both formats

Note: Export links expire after 7 days.

Deleting a Project

Danger: Deleting a project is permanent and cannot be undone.

Pre-Deletion Checklist

Before deleting, ensure you have:

• Exported any translations you need
• Updated applications to stop using this API key
• Informed all team members
• Downloaded any reports or analytics

Deletion Rules

You cannot delete a project if it has translations. To delete:

1. First, delete all translations in the project
2. Then delete the project

This safeguard prevents accidental data loss.

How to Delete

1. Go to Projects list
2. Find the project and click Delete
3. Confirm the deletion

What Gets Deleted:

• The project and all settings
• API key (immediately invalidated)
• Team member associations
• Import/export logs
• CDN files are removed

Best Practices

One Project Per Application

Keep each application in its own project:

• Clear separation of concerns
• Independent API keys and rate limits
• Easy quota tracking per app

Meaningful Names

Use descriptive names that identify the project:

• Good: "Customer Portal - Production", "Mobile App Backend"
• Bad: "Project 1", "Test", "New"

This provides:

• Independent API keys per environment
• Ability to test translation changes before production
• Separate rate limit tracking

Quota Distribution

If you have multiple projects:

• Set explicit limits on high-usage projects
• Leave one project with limit 0 to use "remaining" quota
• Monitor usage patterns and adjust limits

Security

• Rotate API keys periodically (every 90 days recommended)
• Never commit API keys to version control
• Use environment variables (.env files)
• Different keys for development vs production

Troubleshooting

"Project limit reached"

Your subscription tier has a maximum number of projects. Options:

• Delete unused projects
• Upgrade your subscription
• Contact support for assistance

API Key not working

1. Check if the key is enabled (not disabled)
2. Ensure you're using the complete key (no truncation)
3. Check if the key was regenerated recently

Can't add team member

• User must have a Project Collaborator role in the account first
• Project Admins are added automatically (can't add them again)
• Check that user belongs to the same account

Import failing

• Verify file format (.php or .json)
• Check for syntax errors in uploaded files
• Ensure target locale is assigned to the project
• File size must be under 10MB

Next Steps

• Managing Translations - Work with translation keys and values
• AI Translations - Use AI to translate content
• Laravel Client Integration - Connect your application