Extension integration

Step-by-step instructions for GitHub

1. Create a Crowdin configuration file

   Within your TYPO3 extension repository, create a .crowdin.yml file at root with the following content:

   EXT:my_extension/.crowdin.yml

   preserve_hierarchy: 1
   files:
     - source: /Resources/Private/Language/*.xlf
       translation: /%original_path%/%two_letters_code%.%original_file_name%
       ignore:
         - /**/%two_letters_code%.%original_file_name%

   Copied!

2. Connect your GitHub repository

   In order for Crowdin to manage translations, you need to somehow push the translation sources from GitHub to Crowdin. Crowdin provides two different connection options, which are described below.

   Option A: Use the Crowdin <> GitHub integration

   1. Configure the GitHub integration

      In the Crowdin project settings, go to the Integrations tab and click on the button "Browse Integrations", then choose "GitHub". Follow the instructions to connect your GitHub repository to Crowdin.

      Once installed, the Integrations tab will show the GitHub integration with a button to "Set Up Integration". Click on it and choose the mode "Source and translation files mode".

      At this point, Crowdin will request additional permissions to access your repository. You should accept the default permissions and click on the "Authorize crowdin" button.

      Then follow the instructions to configure the integration:

      1. Select the repository from the list of your GitHub repositories.
      2. Select the branch to use for synchronization (usually main or master). When ticking the branch, Crowdin will suggest a "Service Branch Name" l10n_main (or l10n_master), which is the branch where Crowdin will push the translations. You can keep the default value.
      3. Click the pencil icon next to the Service Branch Name to edit configuration.
      4. When asked for the Configuration file name, change it from crowdin.yml to .crowdin.yml and click "Continue". This will effectively use the configuration we created in Step 1 and ensure that everything is properly configured for your TYPO3 extension.
      5. Click the "Save" button to save the configuration.
      6. Back to the main GitHub integration page, you should see a circled checkmark next to the Service Branch Name, indicating that the integration is correctly set up.
      7. Ensure the checkbox "One-time translation import after the branch is connected" is ticked.
      8. Do not tick the checkbox "Push Sources" as the sources are already in the repository and changes are managed within the extension repository and not in Crowdin.
      9. Click the "Save" button to save the configuration of the integration.

   2. Import existing translations

      In case you have local translations, you may do a one-time import by using the Crowdin web interface and manually importing a zip file with the existing translations.

      To prepare the zip file, you can use the following command:

      zip translations.zip Resources/Private/Language/*.*.xlf

      Copied!

      Then go to the Crowdin project, click on the "Translations" tab and drag and drop the zip file into the area "Upload existing translations".

      Note

      The import will work best only if the translation files contain both the <source> and <target> elements. If the <source> elements are missing, Crowdin will not be able to match the translations with the original English labels.

   Option B: Create a GitHub workflow

   When working with GitHub Actions, you can easily integrate the Crowdin GitHub Action into your CI workflow.

   1. Configure GitHub secrets

      First, add the following GitHub secrets to your GitHub repository:

      Secret	Description
      CROWDIN_PROJECT_ID	Project ID, can be found in project settings when navigating to Tools > API.
      CROWDIN_PERSONAL_TOKEN	API key used for authentication at Crowdin, can be generated in personal settings at API > Personal Access Tokens.

   2. Create GitHub workflow

      Now create a new GitHub workflow crowdin.yaml:

      EXT:my_extension/.github/workflows/crowdin.yaml

      name: Crowdin
      on:
        push:
          branches:
            - main
      
      jobs:
        sync:
          name: Synchronize with Crowdin
          runs-on: ubuntu-latest
          steps:
            - uses: actions/checkout@v4
      
            - name: Upload sources
              uses: crowdin/github-action@v2
              env:
                GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
              with:
                config: '.crowdin.yaml'
                project_id: ${{ secrets.CROWDIN_PROJECT_ID }}
                token: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}
                upload_sources: true
                upload_translations: false
                download_sources: false
                download_translations: false

      Copied!

      See also

      For more information about available configuration options, consult the official GitHub action documentation.

   3. Push sources

      For each push in your main branch, the workflow will now transfer all your translation sources to Crowdin.

Happy translating!