Add scripts to allow addons from personal repos to be synchronized with Crowdin

[nvdaes]

This pull request introduces a complete, automated workflow for synchronizing translations with Crowdin, including new scripts, a scheduled GitHub Actions workflow, and supporting documentation. The main changes add Python and PowerShell scripts for translation status checking and synchronization, a workflow for scheduled and manual Crowdin sync, language mapping configuration, and documentation updates. These improvements enable seamless translation management for add-on projects.

Specifically:

• The .github/scripts folder includes:
• setOutputs.py: Allows to write the addonId, extracted from buildVars.py, to the github output environment variable in GitHub Actions.
• • checkTranslation.py: Makes possible to calculate the score (percentage of translated strings) of files (.po, .xliff or .md), using the Crowdin API. This is useful to prevent untranslated files to be included in the add-on folder, reducing the add-on size and avoiding that poor documentation can be accessed when the Help button is pressed from the store.
• crowdinSync.ps1: This script generates/updates an xliff file from the readme.md, creates the pot file and upload these updated source files to Crowdin; commits the updated xliff file to the add-on repo; exports translations from Crowdin, imports translated files with a score/percentage of 50 % or more including these to the addon/locale/lc_messages (po files) or addon/doc (documentation) in the corresponding languages. If translatied files are poor (with low percentages), and a translated file is available inside the add-on, it's considered caming from an old translation produced with the legacy translation system, and it's uploaded to Crowdin. Then changes in the add-on repo are commited to a dedicated branch.
• languageMappings.json: these are mappings between folders used in the add-on, like es, and Crowdin languages, like es-ES (this may need reviewed with advice from NV Access, since for example ne or ga aren't well mapped).
• markdownTranslate.py: Used to generate the xliff file.

[nvdaes]

Purpose

Add-on authors may wish to help translators use Crowdin, the same framework where they translate NVDA. to translate messages and documentation for maintained add-ons:

Other details

• Pot file are created/updated, and uploaded to a Crowdin project.
• The readme.md file is converted to xliff and uploaded to a Crowdin project.
• Po and xfiles are translated.
• Translated files are downloaded and processed to be copied to locale/langCode/LC_MESSAGES/nvda.po, and doc/langCode/readme.md, in the addon folder.
  Authors need to store a Crowdin token with permissions to upload files to the Crowdin project as a repository secret.

Development approach

A workflow (GitHub Actions), and several scripts (Python and Powershell), as well as a json file with language mappings have been added.
Also NV Access l10nUtil.exe is used to synchronize files between the add-on and Crowdin, and to convert between xliff and markdown formats.

[nvdaes]

I've tested that all check pass using this pyproject.toml file on this PR:

nvdaes/translateNvdaAddonsWithCrowdin#11

I use precommit, CodeQL and a workflow to check that all translatable messages have comments for translators.

I'll try to use the cache action to cache some add-on metadata like its id, and also hashfiles from l10nSources (taking the value of buildVars.py), and the hasf¡hfile of the readme.md, to determine if pot and xliff files should be updated.

[nvdaes]

Export translations to Crowdin running the workflow with update=False works properly:

https://github.com/nvdaes/translateNvdaAddonsWithCrowdin/actions/runs/19802210157

[nvdaes]

This time, updatexLiff is failing. Seems that adding blank lines to readme may cause problems:

https://github.com/nvdaes/translateNvdaAddonsWithCrowdin/actions/runs/19802391926/job/56731562709

[nvdaes]

If someone can help with this issue when update xliff, I'll be grateful.
I think that this is one of the bugest problems with xliff files. Sometimes sel lines are None and they don't have a strip method. I don't know if this should be also improved in NVDA
cc: @seanbudd

[seanbudd]

It might be easier to avoid xliff and just translate the markdown files directly. This won't support diffs very well but worth experimenting with

[nvdaes]

@seanbudd wrote:

It might be easier to avoid xliff and just translate the markdown files directly. This won't support diffs very well but worth experimenting with

OK.

[nvdaes]

@CyrilleB79, you were interested in this framework. If you want, feel free to see how the translateNvdaAddonsWithCrowdin.md can be translated in the project. Using xliff files is causing problems, as mentioned, and we are experimenting uploading md files instead.

[abdel792]

Thanks @nvdaes!

Glad we're aligned on this approach.

I’m a bit busy with work at the moment, but I won’t hesitate to jump in and collaborate on the l10nUtil.exe PR as soon as I have some time available.

And yes, in the meantime I can keep an eye on this PR and continue contributing where I can.

Thanks again — really appreciate the collaborative work.

[wmhn1872265132]

I strongly recommend removing the code that handles Markdown translation. I have reviewed the changes to the Simplified Chinese documentation of hkatic/clock@157726d. After uploading the local Markdown document to Crowdin and downloading it again, some translations were lost and the document format had changed. Additionally, having both XLIFF and Markdown format document files in Crowdin at the same time can cause confusion for translators.

[nvdaes]

Please @abdel792 , when you can, look at @wmhn1872265132 comment about markdown. I'm not a translator and I don't know how to proceed about this.

[abdel792]

Hi @wmhn1872265132,

Thank you for your feedback.

I believe the issue is not related to the fact that both Markdown and XLIFF formats are available in Crowdin.

When working with Crowdin, translations for documentation files—whether they are Markdown or XLIFF—must strictly preserve the structure and string order defined in the source language file. If even a single string becomes inconsistent with the original English source file, Crowdin may reject that translation segment during synchronization or export.

For this reason, I strongly recommend that translators always verify the structure of the English source files before starting their work.
This can be done with:

l10nUtil.exe downloadTranslationFile en clock.md -c addon
l10nUtil.exe downloadTranslationFile en clock.xliff -c addon

For translators working directly in the Crowdin web interface, it is equally important to ensure that translated strings remain consistent with the source strings and document structure.

Using Crowdin as our translation platform requires us to be aware of this constraint. In my opinion, the presence of both Markdown and XLIFF formats is not the cause of the issue. On the contrary, it provides greater flexibility for translators, allowing them to choose the format they are most comfortable working with.

The crowdinL10.yml workflow is designed to handle both formats and will automatically download the most complete translation available. The important point is that translations—regardless of whether they are performed in Markdown or XLIFF—must remain structurally consistent with the English source files to avoid rejected translation segments.

Therefore, my recommendation would be to focus on validating the source file structure and translation consistency rather than removing support for one of the documentation formats.

[wmhn1872265132]

When working with Crowdin, translations for documentation files—whether they are Markdown or XLIFF—must strictly preserve the structure and string order defined in the source language file. If even a single string becomes inconsistent with the original English source file, Crowdin may reject that translation segment during synchronization or export.

No, that is not the case for Markdown files. Even if the structure of your uploaded file matches the English source file exactly, issues still occur. I have run tests on this. XLIFF files do not have this problem, but Markdown files do.

For translators working directly in the Crowdin web interface, it is equally important to ensure that translated strings remain consistent with the source strings and document structure.

The web interface may not have this problem because its processing mechanism differs from directly uploading Markdown files.

Using Crowdin as our translation platform requires us to be aware of this constraint. In my opinion, the presence of both Markdown and XLIFF formats is not the cause of the issue. On the contrary, it provides greater flexibility for translators, allowing them to choose the format they are most comfortable working with.

No, having two files with identical content but different formats actually creates confusion for translators: which file should I translate? If I translate the XLIFF but someone else translates the Markdown file, it results in duplicated work.

Therefore, my recommendation would be to focus on validating the source file structure and translation consistency rather than removing support for one of the documentation formats.

Only Markdown files need to be considered regarding structural issues. For XLIFF files, there are two scenarios:

• When translating via the web interface or Poedit, the structure will always remain consistent with the source text.
• When converting an already translated Markdown file into XLIFF using the relevant commands from markdownTranslate.py and uploading the converted file to Crowdin, the conversion will fail if the structure of the Markdown file differs from the English source file.

By the way, there is another issue with Crowdin's Markdown support: it changes certain Markdown formatting markers to its own preferred style. For example, the list marker in the original text is *, but in the Markdown file downloaded from Crowdin, the list marker becomes -. Therefore, I really don't see much need to support Markdown in Crowdin.

[abdel792]

Hi @wmhn1872265132,

Thank you for your detailed feedback and for taking the time to investigate these issues.

I respect your point of view, especially given your experience as a translator and the testing you have performed regarding Crowdin's Markdown handling. Your explanations about the Markdown-specific issues and the potential confusion caused by maintaining both Markdown and XLIFF translations are valuable.

After reviewing the current workflow, it appears that moving to an XLIFF-only approach would require changes to the crowdinSync.ps1 script, and possibly some adjustments to the overall synchronization process. While this should be achievable, it will require some additional work and testing to ensure that the workflow continues to operate correctly.

I'm not sure what @nvdaes thinks about this yet, but based on your findings, it may be worth discussing whether we should simplify the workflow and rely exclusively on XLIFF for documentation translations.

As for me, I'm currently quite busy with work and have less time than usual to contribute to the project, which is why I haven't been participating as actively in this discussion recently. However, I wanted to acknowledge your feedback and the effort you put into analyzing the issue.

Thanks again for sharing your observations and test results.

[CyrilleB79]

Hi all

I do not follow very well this PR / discussion.
But IMO, providing only one file format for translation is preferable.
I expect that not everyone will use this standard workflow, more because times goes on and people tend to use alternative solutions in the meantime.
So I think that xliff format should now be preferred, not direct .md.
.po was still better IMO (e.g. for fuzzy strings when there are slight updates), but IIRC, it was not compatible with this workflow, was it?

[abdel792]

Hi @nvdaes,

Following the recent comments from @wmhn1872265132 and @CyrilleB79, I took another look at the current implementation of crowdinSync.ps1 and the documentation synchronization workflow.

Both comments seem to point in the same direction: simplifying the translation workflow by relying on a single documentation translation format rather than maintaining both Markdown and XLIFF translations in parallel.

Based on the current implementation, one possible approach would be to use XLIFF as the only format exchanged with Crowdin, while continuing to store documentation in Markdown format within the repository.

The main changes in crowdinSync.ps1 would be:

• Stop processing translated Markdown files downloaded from Crowdin.
• Stop uploading translated Markdown files back to Crowdin as fallback translations.
• Remove the logic that evaluates and compares Markdown and XLIFF translation scores.
• Remove the selection mechanism that chooses between the Markdown and XLIFF versions based on translation completeness.
• Keep generating the source XLIFF file from readme.md using md2xliff.
• Keep importing translated XLIFF files from Crowdin and converting them back to Markdown using xliff2md.
• Use XLIFF as the single source of truth for documentation translations.
• Ignore any legacy Markdown translation files that may still exist on Crowdin.

This would simplify the workflow to:

readme.md
    -> md2xliff
    -> Crowdin
    -> translated xliff
    -> xliff2md
    -> translated readme.md

instead of maintaining both Markdown and XLIFF translation files simultaneously.

I have prepared an updated version of crowdinSync.ps1 implementing this approach and attached it for review. Since GitHub comments do not allow PowerShell script attachments directly, I renamed the file to .txt before attaching it to the discussion.

Of course, before making any changes to this PR, I would like to hear your opinion on this direction. Since this would change the current translation workflow, I think it is important to confirm that we all agree with the proposed approach before proceeding.

As a side note, I have been quite busy with work recently, so I may not be able to react as quickly as usual, but I wanted to share this analysis and the proposed update for discussion.

Thanks.
crowdinSync.txt

[CyrilleB79]

@abdel792 and @nvdaes thanks for all the work.

Would it be possible for translators to migrate legacy .md to xliff, as we did for NVDA?
Of course, the translated .md structure should match exactly the structure of the English one.

If not possible, translators will have to retranslate, but some add-ons have quite big documentation files...

[abdel792]

Hi @CyrilleB79,

Thank you for your very relevant and helpful comments.

As far as I remember, I read a message from @seanbudd on the NVDA translations mailing list indicating that, unfortunately, migrating to XLIFF effectively resets the translation state and requires translators to start over with their existing documentation translations.

The l10nUtil.exe md2xliff command recently added by @nvdaes is intended to be used on the source documentation file (the English version) to generate the XLIFF source file. As far as I understand, it is not designed to convert already translated Markdown files into reusable XLIFF translations.

Of course, I may be mistaken, and I would be happy to be corrected if someone has additional information or experience with migrating existing translated Markdown files to XLIFF.

Thanks again for raising this important point.

[wmhn1872265132]

Would it be possible for translators to migrate legacy .md to xliff, as we did for NVDA? Of course, the translated .md structure should match exactly the structure of the English one.

You can convert a translated Markdown file to an XLIFF file by running the following command in the root directory of the NVDA or nvdaL10n repository:

uv run source\markdownTranslate.py translateXliff -x "SourceXLIFFPath" -l LanguageCode -p "MarkdownFile" -o "OutputFile"

However, please note the following issues:

• The structure of the translated file must be exactly the same as the source file. This requirement is identical to that for previous conversions of NVDA documentation. However, possibly due to issues with previous add-on documentation conversions, very few documents have a structure that exactly matches the original source file. You must manually modify the structure to align it.
• SourceXLIFFPath refers to addonId.xliff in the relevant add-on repository.

After that, upload the converted XLIFF file to Crowdin to complete the translation.

[wmhn1872265132]

.po was still better IMO (e.g. for fuzzy strings when there are slight updates)

As far as I know, when downloading files from Crowdin, even the fuzzy string in .po files seems to be lost, requiring a complete retranslation unless a web interface is used.

[nvdaes]

Thanks @abdel792 and @CyrilleB79 .
@CyrilleB79 , I'm not sure if old markdown files can be converted to xliff easily. In my experience, I think that it's very difficult since, in the conversion made by Ikiwiki and our formatting process, the transformation between English and translated documentation may not be "perfect". But I think that there are translators which have produced translated xliff files successfully from markdown. Translators can always use copy-paste from Poedit. I'm not a translator, so I'm not sure about the best approach.

@abdel792 , in general, seems that your crowdinSync attached file is right.
I think that it has an inconsistency in the way that po and documentation files are checked to look at the translated percentage. In xliff files, the threshold (which may be configurable via GitHub Actions vars), as requested by @seanbudd ; while in po files, in your modified script we are looking for exit code. In my last version of the Python script I tried to remove exit codes staff, so that thresholdshould be always consulted instead of exit codes.
Of course, I may be wrong. Please check this again and feel free to commit changes.

Aside note: My job requires working in a non regular scheduled time. This past night I was working until 1 AM, and this weekend I'll work today in the evening/night, and tomorrow in the morning. I'm a captioner working at requested events which require some previous work (for example, this weekend church pope will stay here in Spain, so my work will finish in the night and will start tomorrow in the morning). So I'll need to sleep, in addition to personal life.
So please apologies if I cannot reply as quick as usual too.
Thanks, and please feel free to pay attention to Sean review if needed.

[abdel792]

Hi @nvdaes,

Thank you for your feedback, and thank you @wmhn1872265132 for the additional information regarding Markdown-to-XLIFF migration and PO file handling.

@wmhn1872265132, your explanation about the translateXliff command was very helpful. It is good to know that migration from existing translated Markdown files to XLIFF may be possible, even if manual adjustments may be required when the translated document structure no longer matches the English source document.

@nvdaes, after reviewing your comments regarding the PO translation checks, I have prepared an updated version of crowdinSync.txt.

In addition to the previously proposed XLIFF-only documentation workflow, this version updates the PO processing logic so that both PO and XLIFF files consistently use the translation percentage threshold (MIN_PERCENTAGE_TRANSLATED) rather than relying on Python exit codes.

This should make the validation process more consistent across all translation file types and better align with the current behavior of checkTranslation.py.

As before, the attached file has been renamed from crowdinSync.ps1 to crowdinSync.txt so that it can be attached and reviewed within the GitHub discussion.

Please have a look when you have time and let me know whether you think this updated version addresses the remaining concerns before I commit any changes to the l10n branch.

Also, thank you for the explanation regarding your work schedule. No worries at all about response times; real life and work always come first.

Thanks again to everyone for the constructive discussion.

crowdinSync.txt

[nvdaes]

@abdel792 , seems that $scoreXliff = 0.0 is used, but it's not the same when evaluating the po score. I don't know if this is intentional.
Also, if you want, please update the documentation and test this, or I'll do it when possible.
Thanks.

[abdel792]

Hi @nvdaes,

Thank you again for your review and feedback.

Following your latest comments, I have updated both attached files:

• crowdinSync.txt
• readme.md

In crowdinSync.txt, I updated the PO processing logic so that it follows the same translation score evaluation approach as the XLIFF processing logic. I also initialized $scorePo in the same way as $scoreXliff for consistency.

In readme.md, I updated the documentation to reflect the proposed XLIFF-only documentation workflow. I removed references to markdownTranslate.py, since the repository no longer includes that script after the introduction of the md2xliff command in l10nUtil.exe. I also documented the current workflow based on:

readme.md
    -> md2xliff
    -> Crowdin
    -> translated xliff
    -> xliff2md
    -> translated readme.md

and clarified that legacy Markdown files on Crowdin are ignored by the synchronization process.

I also added documentation regarding the use of the MIN_PERCENTAGE_TRANSLATED threshold, which is now used consistently when evaluating both PO and XLIFF translation completeness.

Regarding the recent comment from @wmhn1872265132, it was interesting to learn that some of the functionality previously provided by markdownTranslate.py could still be useful for migration scenarios. In particular, the translateXliff command he mentioned may help translators migrate existing translated Markdown documentation to XLIFF while preserving part of their previous work, provided that the translated document structure remains compatible with the English source document.

Since md2xliff has already been integrated into l10nUtil.exe through the NVDA localization tooling, it may be worth considering whether additional migration-related functionality from the former markdownTranslate.py script should eventually be added to l10nUtil.exe as well. This could potentially help translators migrate existing documentation more easily if we move forward with the XLIFF-only workflow.

Before any commits are made, I would appreciate it if you could review both attached files and verify that the proposed changes are consistent with the direction you have in mind for this PR.

Please feel free to suggest any additional corrections or improvements before anything is merged.

Thanks again for your time and for all your work on this.
crowdinSync.txt
readme.md

[nvdaes]

@abdel792 , for me, the crowdin sync script seems to be right. I think that in the readme we can add a note about the possibility of using a variable to set the min percentage translated, which can be added to GitHub Actions - variables.
Also, a note about how to update the template by adding it as a remote and using merge with the aalow unrelated histories flag, as commented in this PR. Also, should we include a mechanism to parse this variable? For example, if someone writes a number with words or something which should be null.
Also, we should test this. If you want to test it, for me is OK, or I'll do it when possible.

[nvdaes]

@abdel792 , sorry, abd also what happens if someone writes 100 in the min percentage translated variable, since I think that we are checking if the score is greater than the percentage, not greater or equal.

[abdel792]

Hi @nvdaes,

While testing the workflow and reviewing the threshold logic, I found what appears to be an issue in checkTranslation.py.

In crowdinL10n.yml, MIN_PERCENTAGE_TRANSLATED is defined as a percentage value and defaults to 50 when no GitHub Actions variable is configured. Therefore, the workflow expects values such as 50, 80, or 100.

However, in the getScoreFromApi function, the returned score is currently normalized to a value between 0.0 and 1.0:

return progress / 100

As a result, a translation progress of 93% becomes 0.93, which is then compared against a threshold such as 50. This leads to comparisons like:

0.93 >= 50

which always evaluate to False.

I tested changing line 103 from:

return progress / 100

to:

return progress

and the workflow behaved as expected afterwards.

Test run:
https://github.com/abdel792/dayOfTheWeek/actions/runs/27070359050/job/79898355233

I think this change is necessary so that the score returned by getScoreFromApi uses the same scale as MIN_PERCENTAGE_TRANSLATED.

Could you please have a look and let me know what you think?

Thanks.

[abdel792]

Hi @nvdaes and everyone,

I have just pushed two new commits for review.

The first commit updates the Crowdin synchronization logic to address the concerns raised by @wmhn1872265132 regarding the coexistence of Markdown and XLIFF documentation files in Crowdin.

The main changes are:

• Documentation synchronization now uses XLIFF files as the authoritative translation source.
• Markdown documentation continues to be generated locally from translated XLIFF files using l10nUtil.exe xliff2md.
• The synchronization logic has been updated to match the XLIFF-only workflow discussed in this PR.

Following @nvdaes' review, I also revisited the translation threshold logic and found an issue while testing the workflow.

In crowdinL10n.yml, the threshold is configured through the MIN_PERCENTAGE_TRANSLATED variable and defaults to 50 when no repository variable is defined:

MIN_PERCENTAGE_TRANSLATED: ${{ vars.MIN_PERCENTAGE_TRANSLATED || 50 }}

This indicates that the workflow expects percentage values between 0 and 100.

However, the getScoreFromApi function in checkTranslation.py was returning normalized values between 0.0 and 1.0:

return progress / 100

As a result, a translation progress of 93% became 0.93, which was then compared against percentage thresholds such as 50.

To keep both values on the same scale, I changed the function to return the percentage directly:

return progress

I tested this modification in a workflow run and the threshold validation behaved correctly afterwards:

https://github.com/abdel792/dayOfTheWeek/actions/runs/27070359050/job/79898355233

I also updated the comparison operator from -gt to -ge.

This means that translations reaching exactly the configured threshold are now accepted. For example, if a repository maintainer sets:

MIN_PERCENTAGE_TRANSLATED=100

a file translated at exactly 100% will be synchronized, which seems more intuitive than requiring a value strictly greater than the configured threshold.

The second commit updates the README documentation accordingly.

The documentation now:

• Explains how to configure the MIN_PERCENTAGE_TRANSLATED repository variable.
• Clarifies the distinction between GitHub secrets and repository variables.
• Documents the current XLIFF-based documentation workflow.
• Explains the use of l10nUtil.exe md2xliff and l10nUtil.exe xliff2md.
• Updates the localization workflow documentation to reflect the current implementation.

I also took into account the recent comments from @wmhn1872265132 regarding the migration path from Markdown to XLIFF and the current state of the tooling.

Please review the changes when you have time and let me know if you see anything that should be adjusted before merging.

One additional note regarding the README updates.

I did not document the AddonTemplate update procedure for now.

I understand the workflow that was suggested:

git remote add addonTemplate https://github.com/nvaccess/AddonTemplate.git
git fetch addonTemplate
git branch -u addonTemplate/master
git pull --allow-unrelated-histories

However, in my own tests, especially with add-ons based on older versions of AddonTemplate, the git pull --allow-unrelated-histories step often resulted in a large number of merge conflicts.

My concern is not only the conflicts themselves, but also the possibility of accidentally overwriting add-on-specific metadata while resolving them.

For example, files such as:

• buildVars.py
• pyproject.toml
• changelog.md
• readme.md

typically contain information that is specific to the local add-on repository and should not be replaced by the template version.

These files frequently contain add-on-specific information such as metadata, version history, build configuration, documentation, and release notes that cannot always be merged automatically.

When using git pull --allow-unrelated-histories, Git attempts to merge two histories that may have diverged significantly over time. In practice, this can require extensive manual conflict resolution, and there is a risk of unintentionally losing local metadata or customizations that are specific to the add-on being maintained.

Because of that, I was not fully comfortable documenting this procedure as a general recommendation in the README without additional guidance, warnings, or testing.

I think this topic may deserve a dedicated section in the future explaining the expected conflicts and the best practices for safely merging AddonTemplate updates into existing add-ons, particularly those created from much older template versions.

Thanks everyone for the feedback, testing, and suggestions.

[nvdaes]

@abdel792 , I've reviewed diffs:

git diff HEAD..origin/l10n

And for me this is ready to request a review.

Note: In the documentation, it's recommended to avoiding to run the workflow at the same time if various add-ons are managed. Anyway, as requested by Sean, now the workflow includes a procedure to start with a random delay:

      - name: Random startup delay (0-5 minutes)
        if: github.event_name == 'schedule'
        shell: pwsh
        run: |
          $delaySeconds = Get-Random -Minimum 0 -Maximum 301
          Write-Host "Sleeping for $delaySeconds seconds..."
          Start-Sleep -Seconds $delaySeconds

Anyway, we have also the possibility of collisions even with the random delay.

I have seen your testing workflow. Let's request a review from NV Access.
Thanks everyone.

[abdel792]

Hi @nvdaes,

Thanks for your review and feedback.

I have just pushed an additional documentation update.

Regarding your comment about workflow scheduling, I noticed that the README was still recommending the use of different cron schedules without mentioning the random startup delay that was later added to the workflow.

I have therefore updated the documentation to clarify that the workflow already includes a random delay before scheduled executions, while noting that collisions may still occur in some situations.

I also revisited the GitHub Secrets and Variables section.

Previously, the documentation explained how to create the MIN_PERCENTAGE_TRANSLATED repository variable only after introducing several other repository variables. I felt that this was slightly inconsistent from a reader's perspective, since CROWDIN_PROJECT_ID and L10N_UTIL_CONFIG are also repository variables.

The section has therefore been reorganized so that the process for creating repository variables is introduced before listing the supported variables, making the overall structure more consistent and easier to follow.

Please let me know if you think any further adjustments are needed before requesting the NV Access review.

Thanks again for all your work on this PR.

[nvdaes]

@abdel792 , I've reviewed your last commit, and for me it's right. I requested a review from NV Access, and in fact I think that this PR is ready for review.
Thanks for all your work.