[Bug] dot notation doesn't work properly

[valh1996]

Hi,

I use real sentences as translation keys which can terminate by a dot (.).

The problem is that your current system will translate this (french) :

return [
    "A new verification link has been sent to the email address you provided during registration." => "Un nouveau lien de vérification a été envoyé à l'adresse e-mail que vous avez indiquée lors de votre inscription.",
    "A new verification link has been sent to your email address." => "Un nouveau lien de vérification a été envoyé à votre adresse e-mail.",
]

to german :

return [
'A new verification link has been sent to the email address you provided during registration' => [
        '' => 'Ein neuer Bestätigungslink wurde an die E-Mail-Adresse gesendet, die Sie bei der Registrierung angegeben haben.'
    ],
    'A new verification link has been sent to your email address' => [
        '' => 'Ein neuer Bestätigungslink wurde an Ihre E-Mail-Adresse gesendet.'
    ],
]

The correction would be that in the case where the translation key ends with a dot, with nothing behind it that it doesn't create an unnecessary second level.

[kargnas]

Oh wow. Such a creative way. And your suggestion is also awesome. Happy to accept your pull request.

But anyway you need to change the key to the right key names.

[kargnas]

@claude, suggest to me how to resolve this issue. No changes are also acceptable.

[claude]

Claude finished @kargnas's task —— View job

---

Analysis of Dot Notation Issue

Todo List:

• Read codebase structure and understand translation flow
• Examine PHP language transformer logic
• Identify where dot notation handling occurs
• Analyze root cause of nested array creation
• Provide recommendations and solution options

Root Cause Analysis:
The issue occurs in src/Transformers/PHPLangTransformer.php in the unflattenArray method (line 63):

private function unflattenArray(array $array): array
{
    $result = [];
    foreach ($array as $key => $value) {
        $parts = explode('.', $key);  // <- THE ISSUE IS HERE
        // When key is "A sentence.", this creates ["A sentence", ""]
        // Leading to: 'A sentence' => ['' => 'translation']
    }
}

When This Method Is Called:

• When dot_notation = false (via saveToFile method line 108)
• The unflattenArray method doesn't handle keys ending with dots properly

Configuration Analysis:

• Default config: dot_notation => true
• Transformer fallback: Config::get('ai-translator.dot_notation', false)
• If config is missing, defaults to false (problematic behavior)

Recommendations

Option 1: Quick Fix (Recommended)
Modify the unflattenArray method to handle trailing dots properly:

private function unflattenArray(array $array): array
{
    $result = [];
    foreach ($array as $key => $value) {
        // Skip processing keys that end with dots and have no meaningful parts after
        $parts = explode('.', $key);
        if (end($parts) === '' && count($parts) > 1) {
            // Key ends with dot - treat as literal key
            $literalKey = rtrim($key, '.');
            $result[$literalKey] = $value;
            continue;
        }
        
        // Normal processing for nested keys
        $current = &$result;
        foreach ($parts as $i => $part) {
            if ($i === count($parts) - 1) {
                $current[$part] = $value;
            } else {
                if (!isset($current[$part]) || !is_array($current[$part])) {
                    $current[$part] = [];
                }
                $current = &$current[$part];
            }
        }
    }
    return $result;
}

Option 2: Alternative Solution
Add a configuration option to preserve literal dots:

'preserve_literal_dots' => true,

Option 3: Do Nothing
If this is the intended behavior, consider documenting it clearly for users who use sentences as keys.

Decision Context

• Impact: Affects users who use complete sentences as translation keys
• Frequency: Likely low, but those affected find it confusing
• Complexity: Fix is straightforward
• Breaking Change: No, this would be a bug fix

My recommendation: Implement Option 1 (the quick fix) as it resolves the issue without breaking existing functionality and handles the edge case properly.

---

[kargnas]

@claude, please suggest that I do nothing but detect errors and notify the users. (but I don't want the user to wait for the end of the translation for this. I will want to have streaming output)

[claude]

Claude finished @kargnas's task —— View job

---

Analysis: Streaming Error Detection for Dot Notation Issue

Todo List:

• Analyze current codebase structure and translation flow
• Examine console commands and output systems
• Identify optimal detection points for dot notation issues
• Design streaming notification mechanism
• Propose implementation approach with code examples
• Provide recommendations for user experience

---

Recommended Solution: Streaming Dot Notation Detection

Design Overview

Instead of fixing the bug, implement immediate streaming detection and notification for keys ending with dots that would cause problematic nested arrays.

Implementation Strategy

1. Add Detection Helper Method

Add to BaseTranslateCommand.php:

/**
 * Detect problematic dot notation keys
 */
protected function detectDotNotationIssues(array $keys): array
{
    $problematicKeys = [];
    
    foreach ($keys as $key) {
        // Check if key ends with dot and would create empty nested array
        if (str_ends_with($key, '.')) {
            $problematicKeys[] = $key;
        }
    }
    
    return $problematicKeys;
}

2. Early Detection Point (in getMissingKeys())

protected function getMissingKeys(array $sourceStrings, array $targetStrings): array
{
    $transformer = $this->getTransformer();
    $flatSource = $transformer->flatten($sourceStrings);
    $flatTarget = $transformer->flatten($targetStrings);

    $missingKeys = array_filter(
        array_keys($flatSource),
        fn($key) => !isset($flatTarget[$key]) || trim($flatTarget[$key]) === ''
    );
    
    // 🔥 NEW: Immediate streaming detection
    $problematicKeys = $this->detectDotNotationIssues($missingKeys);
    if (!empty($problematicKeys)) {
        $this->displayWarning("⚠ Dot notation issue detected:");
        foreach ($problematicKeys as $key) {
            $this->displayWarning("  • Key ending with dot: '{$key}'");
            $this->displayWarning("    → This will create nested array: ['" . rtrim($key, '.') . "' => ['' => 'translation']]");
        }
        $this->displayInfo("ℹ Consider using keys without trailing dots for better structure");
    }
    
    return $missingKeys;
}

3. Pre-Translation Warning (in processTranslation())

protected function processTranslation(/* ... */): void {
    $totalCount = count($missingKeys);
    $this->displayInfo("ℹ Found {$totalCount} strings to translate");
    
    // 🔥 NEW: Pre-translation dot notation check
    $problematicKeys = $this->detectDotNotationIssues($missingKeys);
    if (!empty($problematicKeys)) {
        $count = count($problematicKeys);
        $this->displayWarning("⚠ {$count} keys with dot notation issues will be processed");
        $this->displayWarning("  These keys end with dots and will create nested arrays");
        if (!$this->option('non-interactive')) {
            if (!$this->confirm("Continue with translation?", true)) {
                $this->displayWarning("⚠ Translation cancelled");
                return;
            }
        }
    }
    
    // ... rest of existing code
}

4. Real-time Detection (in applyTranslations())

protected function applyTranslations(/* ... */): void {
    foreach ($translations as $item) {
        if ($item['status'] === TranslationStatus::SUCCESS) {
            // 🔥 NEW: Real-time dot notation detection
            if (str_ends_with($item['key'], '.')) {
                $this->displayWarning("⚠ Applying dot notation key: '{$item['key']}'");
                $this->displayWarning("  → Creates nested structure: ['" . rtrim($item['key'], '.') . "' => ['' => '{$item['translated']}']]");
            }
            
            $targetStrings = $transformer->unflatten($targetStrings, $item['key'], $item['translated']);
            $this->displayTranslation($item['key'], $item['translated']);
        }
        // ... rest of existing code
    }
}

User Experience Benefits

1. Immediate Feedback: Users see warnings as soon as problematic keys are detected
2. No Waiting: Detection happens before expensive AI translation calls
3. Clear Explanation: Users understand exactly what will happen
4. Choice: Users can choose to continue or stop the process
5. Real-time Monitoring: See exactly which keys are causing issues during processing

Example Console Output

⚠ Dot notation issue detected:
  • Key ending with dot: 'A new verification link has been sent to the email address you provided during registration.'
    → This will create nested array: ['A new verification link has been sent to the email address you provided during registration' => ['' => 'translation']]
  • Key ending with dot: 'A new verification link has been sent to your email address.'
    → This will create nested array: ['A new verification link has been sent to your email address' => ['' => 'translation']]
ℹ Consider using keys without trailing dots for better structure

⚠ 2 keys with dot notation issues will be processed
  These keys end with dots and will create nested arrays
Continue with translation? (yes/no) [yes]:

Implementation Notes

• Zero Performance Impact: Detection is O(n) on keys, happens once per file
• Backward Compatible: Doesn't change existing behavior, only adds warnings
• Configurable: Could add config option to disable warnings if needed
• Extensible: Easy to add more detection patterns in the future

Additional Considerations

1. Configuration Option: Add 'warn_dot_notation' => true to config
2. Quiet Mode: Skip warnings in non-interactive mode if desired
3. Logging: Could also log these warnings to Laravel logs for debugging

This solution provides immediate, streaming feedback to users about dot notation issues without changing the core functionality, giving users full awareness of what's happening with their translation keys.

---