[BUG] Matrix Version Doesn't Match Translations

by ADMIN 48 views

Introduction

In this article, we will explore a bug that occurs when using the matrix approach in Crowdin to download translations. The issue arises when the matrix version doesn't match the translations, resulting in omitted translations. We will delve into the configuration file crowdin.yml and the project structure to identify the root cause of the problem.

Project Structure

The project structure is as follows:

  • Docs are stored in a subfolder /docs/.
  • Source is docs/en/, and translations are all other folders sorted by 2-letter language codes, such as docs/ko/.

Crowdin.yml Configuration

The crowdin.yml file is located in the root of the docs folder and contains the following configuration:

"project_id_env": "CROWDIN_PROJECT_ID"
"api_token_env": "CROWDIN_PERSONAL_TOKEN"
"base_path": "../"

"preserve_hierarchy": true

"files": [
  {
    "source": "/docs/en/**/*.md",
    "ignore": ["/docs/en/_sidebar.md",],
    "translation": "/docs/%two_letters_code%/**/%original_file_name%"
  }
]

Note the preceding slash on the source path.

Workflow

The workflow is defined in the .github/workflows/docs_crowdin_download.yml file and references the crowdin.yml file. It runs a matrix on the downloaded translations, following the format of the Crowdin GitHub Action documentation.

Issue

The issue arises when the matrix version doesn't match the translations. As shown in the action run, the source file en/advanced/community_supported_dev_env.md is matched by the translation ko/en/advanced/community_supported_dev_env.md, which doesn't match the mapping defined in the crowdin.yml file.

Relevant Action Run Output

The relevant bits of the action run output are shown below:

⚠️  Downloaded translations don't match the current project configuration. The translations for the following sources will be omitted (use --verbose to get the list of the omitted translations):
	- en/msg_docs/UavcanParameterValue.md (1)
	- en/msg_docs/VehicleLocalPositionSetpoint.md (1)
	- en/frames_vtol/vtol_quadplane_falcon_vertigo_hybrid_rtf_dropix.md (1)
	- en/concept/flight_modes.md (1)
	- en/flight_modes_fw/hold.md (1)
...
	- en/msg_docs/VehicleOdometry.md (1)
	- en/msg_docs/UnregisterExtComponent.md (1)

Comparison with Similar Project

The project structure and crowdin.yml configuration were copied from a similar project, qgroundcontrol, which correctly maps the files. The only difference is the use of the matrix approach in the current project.

Advice

Based on the analysis, the issue is likely due to a configuration issue with the crowdin.yml file. To resolve the issue, we recommend the following:

  1. Review the crowdin.yml file and ensure that the source and translation paths are correctly defined.
  2. Check the project structure and ensure that the source and translation files are correctly organized.
  3. Verify that the matrix approach is correctly configured in the workflow.
  4. Compare the crowdin.yml file and project structure with the similar project, qgroundcontrol, to identify any differences.

Q: What is the matrix approach in Crowdin?

A: The matrix approach in Crowdin is a feature that allows you to download translations for multiple languages in a single workflow. It enables you to separate PRs (pull requests) for each target language, making it easier to manage and review translations.

Q: What is the issue with the matrix approach in this case?

A: The issue arises when the matrix version doesn't match the translations. In this case, the source file en/advanced/community_supported_dev_env.md is matched by the translation ko/en/advanced/community_supported_dev_env.md, which doesn't match the mapping defined in the crowdin.yml file.

Q: What is the difference between the crowdin.yml file in this project and the similar project, qgroundcontrol?

A: The only difference is the use of the matrix approach in the current project. The crowdin.yml file and project structure were copied from qgroundcontrol, which correctly maps the files.

Q: How can I resolve the issue with the matrix approach?

A: To resolve the issue, we recommend the following:

  1. Review the crowdin.yml file and ensure that the source and translation paths are correctly defined.
  2. Check the project structure and ensure that the source and translation files are correctly organized.
  3. Verify that the matrix approach is correctly configured in the workflow.
  4. Compare the crowdin.yml file and project structure with the similar project, qgroundcontrol, to identify any differences.

Q: What are some common mistakes to avoid when using the matrix approach in Crowdin?

A: Some common mistakes to avoid when using the matrix approach in Crowdin include:

  • Incorrectly defining the source and translation paths in the crowdin.yml file.
  • Failing to correctly organize the source and translation files in the project structure.
  • Not verifying that the matrix approach is correctly configured in the workflow.
  • Not comparing the crowdin.yml file and project structure with similar projects to identify differences.

Q: How can I troubleshoot issues with the matrix approach in Crowdin?

A: To troubleshoot issues with the matrix approach in Crowdin, we recommend the following:

  • Review the crowdin.yml file and project structure to ensure that they are correctly defined.
  • Check the workflow configuration to ensure that the matrix approach is correctly configured.
  • Verify that the source and translation files are correctly organized in the project structure.
  • Compare the crowdin.yml file and project structure with similar projects to identify differences.

Q: What are some best practices for using the matrix approach in Crowdin?

A: Some best practices for using the matrix approach in Crowdin include:

  • Clearly defining the source and translation paths in the crowdin.yml file.
  • Correctly organizing the source and translation files in the project structure.
  • Verifying that the matrix approach is correctly configured in the workflow.
  • Comparing the crowdin.yml file and project structure with similar projects to identify differences.
  • Regularly reviewing and updating the crowdin.yml file and project structure to ensure that they remain accurate and up-to-date.