Dark Translation Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require cursedcoder/dark-translation-bundle
   

   Register the bundle in AppKernel.php and include its routes in routing.yml.

2. Configuration: Add your GitHub fork URL for the target language and local paths for source/docs in config.yml:

   dark_translation:
       repositories:
           ru: 'https://github.com/your-fork/symfony-docs-ru'
       source:
           base_dir: '%kernel.root_dir%/../docs'
           from: '%kernel.root_dir%/../docs/symfony-docs'
           to: '%kernel.root_dir%/../docs/translated'
   

3. First Use Case: Fetch the latest Symfony docs for translation:

   php app/console dark:translation:fetch
   

   Access the translation interface at /dark/translation to start editing.

Implementation Patterns

Workflow for Translating Docs

1. Fetching Docs: Use the dark:translation:fetch command to pull the latest Symfony docs into your local from directory.

   php app/console dark:translation:fetch --lang=ru
   

2. Editing Interface: Navigate to /dark/translation to use the double-editor with synchronized scrolling. The left panel shows the source (English), and the right panel shows the target language (e.g., Russian).

3. Saving Translations: After editing, save changes to the to directory. The bundle tracks changes and allows you to push translations to your fork later.

4. Pushing Translations: Commit and push translations to your GitHub fork:

   php app/console dark:translation:push --lang=ru
   

Integration Tips

• Custom Themes: Override the default Symfony.com theme by extending the Twig templates in DarkTranslationBundle::Resources/views.
• Localization Workflow:
  • Use the dark:translation:generate command to create missing translation files in the to directory.
  • Leverage the visual translation widget for real-time comparison and editing.
• CI/CD Pipeline: Automate fetching/pushing with GitHub Actions or Jenkins. Example:

  # .github/workflows/translate.yml
  jobs:
    translate:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v2
        - run: composer install
        - run: php bin/console dark:translation:fetch --lang=ru
        - run: php bin/console dark:translation:push --lang=ru
  

Gotchas and Tips

Pitfalls

1. File Tracking: The bundle tracks changes via filenames. Ensure your from and to directories mirror each other exactly (same subfolder structure). Mismatches may cause files to be ignored during pushes.

   • Fix: Run dark:translation:sync to align directory structures.

2. GitHub Fork Permissions: The dark:translation:push command requires write access to your fork. Test with a personal access token if using SSH:

   git config --global url."git@github.com:".insteadOf "https://github.com/"
   

3. Twig Template Overrides: Overriding templates requires careful naming. Use the bundle’s namespace in your app/Resources/DarkTranslationBundle/views/ directory to avoid conflicts.

Debugging

• Command Errors: Check the dark_translation config for typos in repositories or source paths. Use --verbose flag for commands:

  php app/console dark:translation:fetch --lang=ru --verbose
  

• Missing Files: If files appear missing in the editor, verify the from directory contains the original docs. Re-fetch with:

  php app/console dark:translation:fetch --force
  

Extension Points

1. Custom Commands: Extend the bundle by creating your own commands (e.g., dark:translation:validate to check translation completeness). Use the existing command classes as a reference:

   // src/Dark/TranslationBundle/Command/ValidateCommand.php
   class ValidateCommand extends ContainerAwareCommand {
       protected function execute(InputInterface $input, OutputInterface $output) {
           // Custom logic here
       }
   }
   

2. Hooks for Pre/Post-Translation: Override the DarkTranslationEvents to add logic before/after fetching/pushing. Example:

   // src/Acme/TranslationListener.php
   class TranslationListener {
       public function onTranslationFetch(DarkTranslationEvents $event) {
           // Pre-fetch logic
       }
   }
   

   Register the listener in services.yml:

   services:
       acme.translation_listener:
           class: Acme\TranslationListener
           tags:
               - { name: kernel.event_listener, event: dark.translation.fetch, method: onTranslationFetch }
   

3. Localization Rules: Add custom rules for specific file types (e.g., .md vs .rst). Extend the TranslationManager service:

   // config/services.yml
   dark_translation.manager.class: Acme\CustomTranslationManager
   dark_translation.manager.arguments:
       - '@service_container'
       - ['.md' => 'markdown_rules', '.rst' => 'rest_rules']