Crowdin integration

This section will go over the necessary steps for integrating crowdin for translations.

Prerequisites

1. You need to have a crowdin account. If you don’t have one, you can create one here.
2. You need to have a crowdin project. If you don’t have one, you can create one here
3. You need to host your project on github. If you don’t have one, you can create one here

Steps

1. Initialize a new config file if you dont have one already. To do this run the following command:

   jsq config:init

   The file should look like this:

        {
            "outputDirectory": "./docs/build",
            "sourceDirectory": "./dist",
            "translationsDirectory": "./docs/_translations",
        }

   • outputDirectory: The directory where the generated documentation will be stored.
   • languages: An array of the languages you want to support.
   • translationsDirectory: The directory where the translations will be stored. This directory will be used by crowdin to store the translations.

   Make sure the outputDirectory and translationsDirectory exists within your project

2. Generate the documentation using JSquarto. You can follow the steps @usage-basic

3. Commit all necessary changes, including the config.json file and push to your github repository.

4. On your crowdin project, go to the settings page and click on the Integrations tab.

5. Search for Github integration and click on the Install button.

6. Go back to the integrations tab and select find the Github integration then click Set Up Integration

7. Click the dropdown menu for Set Up Integration and select the Source and translation files mode

8. Fill the repository details, specify the branch for translations and translation mode.

9. Now go back to the Integrations tab and select Github Integration.

10. On the integrations page, you’ll see your newlty created project. Open the branch configuration

11. Add Filters for the files you want to translate. You can add filters for the files in the translationsDirectory specified in the config.json file. The filters tell crowdin which files to watch for and where to add the translations for each of them These are the configuration used are;
    

• Source files: /docs/build/**/*.qmd
  
• Translated files path: /docs/_translations/%two_letters_code%/**/%file_name%.%two_letters_code%.qmd.
  
• **/*.qmd tells crowdin to match all files in subdirectories with the .qmd extension.
  

Note that /docs/build and /docs/_translations/ correspond with the values we set for outputDirectory and translationsDirectory in the config.json file.

Using this configuration will ensure that the translations maintain the same structure as the source files. And each translation will be stored in a directory with the language code as the name.

12. Save and proceed to setup the automated build using Github actions. Follow the guide here