Transliteration Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require prinsfrank/transliteration
   

   Ensure your project uses PHP 8.1+.

2. First Use Case: Convert a string to ASCII for a multilingual support system:

   use PrinsFrank\Transliteration\TransliteratorBuilder;
   use PrinsFrank\Transliteration\ConversionSet\ToASCII;
   
   $builder = new TransliteratorBuilder();
   $builder->applyConversionSet(new ToASCII());
   $transliterated = $builder->transliterate('アマゾン'); // Output: 'amazon'
   

3. Where to Look First:

   • TransliteratorBuilder: Core class for constructing transliterators.
   • ConversionSet: Predefined sets like ToASCII, IPAToEnglishApproximation, or ScriptLanguage.
   • README’s "Use Cases": Real-world examples (e.g., customer support, identity verification).

Implementation Patterns

Core Workflow

1. Builder Pattern: Chain methods to construct transliterators:

   $builder
       ->applyConversionSet(new ToASCII())
       ->applyConversionSet(new IPAToEnglishApproximation())
       ->transliterate('naɕi gʌba'); // 'naci guba'
   

2. Conversion Sets:

   • Bundled Sets: Use out-of-the-box (e.g., ToASCII, ScriptLanguage).
   • Custom Sets: Extend ConversionSet interface for domain-specific rules:

     class CustomSet implements ConversionSet {
         public function apply(TransliteratorBuilder $builder): void {
             $builder->addConversion(new Conversion('ß', 'ss'));
         }
     }
     

3. Script/Language Conversion: Convert between scripts (e.g., Cyrillic to Latin):

   use PrinsFrank\Transliteration\ConversionSet\ScriptLanguage;
   use PrinsFrank\Transliteration\Target\ScriptName;
   
   $builder->applyConversionSet(
       new ScriptLanguage(ScriptName::CYRILLIC, ScriptName::LATIN)
   );
   $builder->transliterate('Иван'); // 'Ivan'
   

4. Contextual Replacements: Use Conversion with context (e.g., beforeContext, afterContext):

   $builder->addConversion(
       new Conversion('ß', 'ss', 'beforeContext: e')
   );
   $builder->transliterate('Straße'); // 'Strasse' (only replaces 'ß' before 'e')
   

5. Variable Definitions: Reuse complex patterns:

   $builder->addVariableDefinition(new VariableDefinition('foo', 'bar'));
   $builder->addConversion(new Conversion('{foo}', 'baz')); // Replaces 'bar' with 'baz'
   

Integration Tips

• Validation: Sanitize input before transliteration (e.g., strip HTML).
• Caching: Cache transliterators for repeated use:

  $transliterator = $builder->getTransliterator();
  // Reuse $transliterator later
  

• Error Handling: Wrap transliteration in try-catch for invalid inputs:

  try {
      $result = $builder->transliterate($input);
  } catch (TransliteratorException $e) {
      log($e);
      return $input; // Fallback
  }
  

Gotchas and Tips

Pitfalls

1. Recursive ConversionSets: Nesting A in B and B in A throws an exception. Avoid circular dependencies.

2. Undocumented ICU Rules:

   • beforeContext/afterContext require ICU’s rule syntax.
   • Example: new Conversion('ß', 'ss', 'beforeContext: e') only replaces ß before e.

3. Variable Naming: Variable names in VariableDefinition must be alphanumeric (no special chars). Escaping is automatic for values.

4. Filter Scope: Global filters (e.g., Filter::addRange()) apply to all SingleIDs. Prefer per-ID filters to avoid side effects.

5. PHP Extensions: Requires intl extension. Verify with:

   php -m | grep intl
   

Debugging Tips

1. Inspect Rule Sets: Log the generated ICU rule string for debugging:

   $ruleSet = $builder->getTransliterator()->getID();
   // Output: 'Any-Latin;Latin-ASCII;' (e.g., for ToASCII)
   

2. Test Edge Cases:

   • Empty strings, mixed scripts, or unsupported characters may fail silently. Validate inputs.

3. Performance:

   • Complex rule sets (e.g., nested ConversionSets) slow down transliteration. Benchmark with microtime().

Extension Points

1. Custom Targets/Sources: Extend Target\ScriptName, Target\LanguageTag, etc., for domain-specific tags.

2. Filter Logic: Override Filter::addRange() to implement custom character ranges (e.g., emoji support).

3. Transliterator Caching: Cache built transliterators in a service container (e.g., Laravel’s app binding):

   $this->app->singleton(TransliteratorBuilder::class, function () {
       return new TransliteratorBuilder();
   });
   

4. Laravel Integration: Create a facade or service provider for global access:

   // app/Providers/TransliterationServiceProvider.php
   public function register() {
       $this->app->singleton('transliterator', function () {
           return new TransliteratorBuilder();
       });
   }