Code Scanner

The Code Scanner analyzes hardcoded text in your Laravel application and helps you convert them into proper translation keys. It automates the process of finding translatable strings, creating translations, and updating your source code.

How It Works

The Code Scanner workflow has three main phases:

1. Scan - Run the CLI command to find hardcoded text in your codebase
2. Review - Approve, edit, or reject suggestions in LangSyncer
3. Apply - Update your source files with translation function calls

Phase 1: Scanning Your Code

Running a Scan

From your Laravel project directory, run:

php artisan translator:scan

What Gets Detected

The scanner finds hardcoded text in .blade.php and .php files:

• HTML content in tags (headings, buttons, paragraphs)
• HTML attributes (placeholder, title, alt)
• String literals in PHP code
• Exception messages

Examples:

// HTML content
<h1>Welcome to our app</h1>
<button>Submit</button>

// Attributes
<input placeholder="Enter your email">
<img alt="Profile picture">

// PHP strings
throw new Exception('Invalid credentials');

Scan Options

# Scan specific paths
php artisan translator:scan --path=resources/views --path=app/Http

# Exclude directories
php artisan translator:scan --exclude=tests --exclude=database

# Preview without sending to LangSyncer
php artisan translator:scan --dry-run

# Use AI to enhance key suggestions
php artisan translator:scan --ai

# Filter by minimum confidence (0-100)
php artisan translator:scan --min-confidence=50

# Output format
php artisan translator:scan --format=table
php artisan translator:scan --format=json
php artisan translator:scan --format=csv

Understanding Confidence Scores

Each detected text receives a confidence score:

Factors that increase confidence:

• Known element types (headings, buttons, labels)
• Appropriate text length (5-80 characters)
• User-facing file locations (views, components)

AI-Enhanced Analysis

Adding the --ai flag uses AI to generate significantly better suggestions:

php artisan translator:scan --ai

Example comparison:

AI analysis benefits:

• Semantic keys - Meaningful names like congratulations instead of literal you-did-it-john
• Detects dynamic content - Identifies names, numbers, dates and converts them to placeholders (:name, :count)
• Consistent language - Keys generated in English even for non-English text
• Cleaner values - Removes hardcoded data, adds proper placeholders

Cost: 1 quota unit per candidate

Phase 2: Reviewing Suggestions

After scanning, review the suggestions in LangSyncer.

Accessing the Review Page

1. Go to Code Scanner in the sidebar
2. Select your project
3. Review pending suggestions

Review Interface

Each suggestion shows:

• Original text - The hardcoded string found
• Suggested key - Proposed translation key (e.g., auth.buttons.login)
• Confidence - Color-coded badge
• Locations - Files where this text appears

Available Actions

Editing Suggestions

Click Edit to open the edit modal where you can:

• Change the suggested key
• Modify the translation value
• Add placeholders for dynamic content

The modal offers two save options:

• Save - Save changes but keep the review pending for later approval
• Save & Approve - Save changes and approve immediately

Batch Actions

For efficiency:

• Approve Selected - Approve multiple checked items
• Reject Selected - Reject multiple checked items
• Approve All High Confidence - Auto-approve all 80%+ confidence items

Filtering

Filter the review list by:

• Status - Pending, Approved, Rejected, Approved (Not Applied)
• Confidence - High, Medium, Low
• File path - Search by filename

Phase 3: Applying Changes

After approving reviews, apply the changes to your source code:

php artisan translator:apply

This command does three things:

1. Replaces hardcoded text with Laravel translation functions in your source files
2. Activates translations - moves them from draft to active status
3. Regenerates CDN - updates the CDN with the new translations

Before:

<h1>Welcome to our app</h1>
<button>Submit</button>

After:

<h1>{{ __('home.headings.welcome') }}</h1>
<button>{{ __('buttons.submit') }}</button>

Apply Options

# Preview changes without modifying files
php artisan translator:apply --dry-run

# Skip confirmation prompt
php artisan translator:apply --yes

After Applying

1. Review changes: git diff - check for syntax errors or invalid placements
2. Fix undefined variables: Your IDE will flag invented variable names - replace with real ones
3. Test your application: Run your tests and verify the app works correctly
4. Commit changes: git add . && git commit -m "Apply translations"

Tip: If you find invalid replacements (like __() in property declarations), revert those specific changes with git checkout -p and reject the corresponding review.

Best Practices

Scan Regularly

Run scans:

• After adding new features
• Before releases
• As part of code review

Review Carefully

• Check suggested keys for clarity
• Verify confidence scores match actual quality
• Don't auto-approve everything—review medium/low confidence items

⚠️ Important: The Code Scanner is not 100% accurate in determining valid placement for __() calls. It may suggest translations in contexts where PHP syntax doesn't allow function calls, such as:

• Property declarations (public $placeholder = __('...'))
• Constant definitions
• Array keys in certain contexts

Always review the code context before approving, especially for low/medium confidence items. After applying, check git diff and test your application.

Use Consistent Naming

Good key patterns:

section.type.description

auth.buttons.login
profile.labels.email
errors.validation.required

Handle Dynamic Content

When the scanner detects text with dynamic values (like names, counts, or dates), it may suggest placeholders:

Original: "Welcome, John!" Suggested key: welcome.greeting Suggested value: "Welcome, :name!"

After applying, you'll see:

__('welcome.greeting', ['name' => $name])

⚠️ Manual step required: The scanner generates valid PHP code, but the variable name is invented based on the placeholder. You must replace it with the actual variable from your application:

// Before (auto-generated - $name doesn't exist)
__('welcome.greeting', ['name' => $name])

// After (manually corrected)
__('welcome.greeting', ['name' => $user->name])

Your IDE will likely flag these as "Undefined variable" errors, making them easy to find and fix.

Troubleshooting

Scan Not Finding Text

• Check file paths with --path option
• Ensure files are not in excluded directories
• Verify file types are supported (.blade.php, .php)

Low Confidence Scores

• Text may be too short or generic
• File location not recognized as user-facing
• Consider reviewing manually

Apply Not Working

• Ensure translations are published first
• Check that reviews are approved (not just pending)
• Verify API key configuration

Next Steps

• Translations - Manage your translations
• AI Translations - Auto-translate content
• Quota Management - Understand quotas