Troubleshooting

Common issues and their solutions.

Installation Issues

Package won't install

Error: Package not found

Solution:

1. Clear composer cache and retry
2. Verify the package name is correct

composer clear-cache
composer require headwires/translator-client

Configuration not publishing

Error: Unable to publish configuration

Solution:

php artisan vendor:publish --tag=translator-client-config --force

Translation Issues

Translations not updating

Symptoms: Published changes don't appear in your app

Checklist:

1. Verify translations are marked as Active in LangSyncer
2. Run sync command to pull latest:

   php artisan translator:sync
   

3. If using static mode, regenerate cache:

   php artisan translator:warmup
   

4. Clear Laravel's application cache:

   php artisan cache:clear
   

Missing translations showing raw keys

Symptoms: See messages.welcome instead of "Welcome!"

Checklist:

1. Verify the key exists in LangSyncer
2. Verify translation is Active (not Draft)
3. Check locale matches your app's current locale
4. Check config/translator-client.php fallback settings:

   'fallback_locale' => 'en',
   

Variables not replaced

Symptoms: See :name instead of actual name

Solutions:

• Ensure you're passing variables:

  __('messages.welcome', ['name' => $user->name])
  

• Check variable name matches exactly (case-sensitive)

Wrong locale showing

Symptoms: Getting English when expecting Spanish

Checklist:

1. Verify app()->getLocale() returns expected locale
2. Check middleware is setting locale correctly
3. Verify translation exists for that locale in LangSyncer

Client Mode Issues

Live mode not fetching translations

Symptoms: Changes in LangSyncer not reflected in live mode

Checklist:

1. Verify CLI_TRANSLATOR_MODE=live in .env
2. Verify CLI_TRANSLATOR_API_KEY is set correctly
3. Verify CLI_TRANSLATOR_CDN_URL is set (copy from project's API Key & CDN tab)
4. Ensure translations are Active in LangSyncer

CDN fetch returning 404

Symptoms: translator:sync or translator:warmup fails with "not found" errors

Solution:

1. Ensure CLI_TRANSLATOR_CDN_URL is set in your .env
2. Copy the exact URL from your project's API Key & CDN tab in LangSyncer
3. Verify translations have been published at least once
4. Click Regenerate CDN in the project's Actions modal to refresh CDN files

Static mode cache stale

Symptoms: Old translations despite publishing new ones

Solution:

php artisan translator:sync
php artisan translator:warmup

Add to your deployment script to automate this.

Code Scanner Issues

Scanner not finding translations

Symptoms: Files scanned but no suggestions generated

Checklist:

1. Verify you're scanning .blade.php or .php files
2. Check files contain hardcoded strings (not already using __())
3. Ensure files are in the scanned directory

Scanner false positives

Symptoms: Scanner suggests translating code that shouldn't be translated

Solution: Review suggestions carefully before applying. The scanner may suggest translations in invalid PHP contexts like array keys or constants.

→ Code Scanner Documentation

AI Translation Issues

AI translation failed

Error: AI translation unavailable

Checklist:

1. Verify you have AI quota remaining
2. Ensure source text is not empty
3. Try again in a few minutes

Quota depleted

Solutions:

1. Purchase a quota pack for immediate credits
2. Wait for monthly quota reset (billing cycle)
3. Upgrade to Icebreaker for higher monthly quota

→ Quota Management

Billing Issues

Payment failed

Solutions:

1. Verify card details are correct
2. Check card hasn't expired
3. Ensure sufficient funds
4. Try a different payment method via Manage Billing
5. Contact your bank if declined

Subscription not active

Checklist:

1. Go to Subscription to check status
2. Verify payment completed
3. Look for failed payment notifications
4. Contact support if payment shows successful but subscription isn't active

Common Error Messages

Diagnostic Commands

Check configuration status

php artisan translator:status

Shows:

• Project name
• API Key (configured/missing)
• CDN URL (configured/missing)
• Lang files path
• Mode (static/live/auto)
• Cache TTL
• Webhook status

Getting Help

Before contacting support, gather:

• Error messages (full text)
• Steps to reproduce
• Laravel version (php artisan --version)
• Package version (composer show headwires/translator-client)

Contact support for billing or technical issues.