Many Challenges Faced with Translating NVDA Documentation

[cary-rowen]

Detailed Description of the Issue

As NV Access is in the process of migrating NVDA documentation to Crowdin, I understand this hasn't been fully completed yet. However, as a Chinese translator, I’d like to provide some early feedback in the hopes of making things smoother.

Background

Due to accessibility challenges with Crowdin's web interface, we prefer using Poedit to edit .po files.

The advantages of using Poedit include:

1. NVDA has specific support for Poedit, which significantly boosts productivity.
2. We can import pot templates to keep translations up to date.

General Workflow (using NVDA’s interface translation as an example)

1. Download .pot or .xliff files from Crowdin.
2. Complete or partially complete the translation using Poedit.
3. Upload the translation back to Crowdin.

Issues or Challenges Faced During the User Guide Translation Process

1. We can’t update local translations using a .pot template.
2. If an incomplete translation file is uploaded, two situations can occur:
   • If untranslated entries are pre-filled with the original English text, they will appear as translated once uploaded, making it hard to locate them later.
   • If untranslated entries are left blank, Crowdin will populate them with <target/> upon upload.
3. The UI differences between Crowdin’s web interface and Poedit make it difficult to proofread translations.

Why Aren’t Other Templates Suitable for This Case?

This is early feedback on the translation system migration.

Have You Sought Advice on How to Report This Issue via a Community Discussion? If So, Please Link the Discussion

None

Steps to Reproduce or Illustrate the Issue (if applicable)

n/a

Expected Outcome or Behavior (if applicable)

As I mentioned in comment #17106, we’re hoping for a way to directly edit markdown files. This would provide the following benefits:

1. No need to interact with Crowdin or Poedit interfaces; instead, we can use powerful text editors for search and replace functions.
2. We can preview the final output easily, such as by pressing Ctrl+Shift+V in VS Code.
3. It’s especially useful for correcting existing translations, allowing us to:
   • Search through already translated content.
   • Batch replace incorrect translations.
   • Use regular expressions for complex searches.

Screenshots, Logs, and Other Attachments (if applicable)

n/a

System Configuration or Software Environment (if applicable)

n/a

Additional Information (if applicable)

While Poedit is a tool specifically designed for localization, if the issues mentioned above remain unresolved, it may not be the best choice for NVDA localization efforts.

cc @wmhn1872265132
You can add more details.

[michaelDCurran]

Thanks for this detailed feedback.

However, can you please provide further detail on a few things.

1. We can’t update local translations using a .pot template.

Can you explain this further?
Generally, the pattern should be either:

1. Connect to Crowdin with PoEdit. Choose the po or xliff file to translate. Make changes, and save. Ipprove strings in the Crowdin interface. Or
2. Download the file from Crowdin. Open in PoEdit. Make changes, and save. Upload to Crowdin optionally approving all strings in the file.

Please explain more about updating local translations from a .pot file.

If untranslated entries are pre-filled with the original English text, they will appear as translated once uploaded, making it hard to locate them later.

I agree this would complicate things. The source xliff files we upload to Crowdin does not contain any target tags at all. Are you saying that when you download the partially translated xliff, it already has target tags with the English pre-filled?
Can you provide an example file?

If untranslated entries are left blank, Crowdin will populate them with upon upload.

Do you mean <target /> within the segment tag in the xliff file?
Can you explain the impact of this further? Does PoEdit not treat this as untranslated the next time you open the file?
Can you provide an example file?

We will of course continue to try and improve the workflow here where we can. We have no future plan to to allow translation of the raw markdown at this stage. We want to fully try and solve all issues so that files can be translated in a standard way using PoEdit.

[michaelDCurran]

Re approval of strings:
If approval of strings continues to be a major problem on Crowdin, we could change things so that:

• we no longer force strings to be approved to show up when downloading and exporting. Rather Crowdin will just choose the most recent translation for any given string.
• For security / quality purposes, we would only allow people to join the project on Crowdin via invitation, and it would be up to language coordinators to correct bad translations / ban unhelpful translators.

Would this be more manageable?

[hwf1324]

Can you explain this further? Generally, the pattern should be either:

1. Connect to Crowdin with PoEdit. Choose the po or xliff file to translate. Make changes, and save. Ipprove strings in the Crowdin interface. Or

2. Download the file from Crowdin. Open in PoEdit. Make changes, and save. Upload to Crowdin optionally approving all strings in the file.

Please explain more about updating local translations from a .pot file.

If untranslated entries are pre-filled with the original English text, they will appear as translated once uploaded, making it hard to locate them later.

About pot import

The interface has been translated as an example: download the file from Crowdin and translate it, NVDA has new translation entries to update, you can download nvda.pot from AppVeyor and import it.

About the example file

You can download the Simplified Chinese user guide from Crowdin to view it.

About leaving strings empty

The poedit display is normal, but the uploaded result is problematic.
https://crowdin.com/project/nvda/activity-stream
History of wrong forces in Simplified Chinese translation

The above from @wmhn1872265132

I agree this would complicate things. The source xliff files we upload to Crowdin does not contain any target tags at all. Are you saying that when you download the partially translated xliff, it already has target tags with the English pre-filled? Can you provide an example file?

If untranslated entries are left blank, Crowdin will populate them with upon upload.

Do you mean <target /> within the segment tag in the xliff file? Can you explain the impact of this further? Does PoEdit not treat this as untranslated the next time you open the file? Can you provide an example file?

1. when we open the xliff file using Poedit's cloud translation, the untranslated entries are shown as empty in Poedit.
   1. when we synchronize the translation with Crowdin, all untranslated entries are translated as <target />
2. when we download the translation file, all translation targets have the value of the original English translation with the status “initial”

Even for unapproved translations, the status in xliff seems to be ``translated''

Here's my test from yesterday.

By the way, I spent a lot of time yesterday deleting a lot of invalid translations I'd uploaded that would have swamped the ones that worked

I can't delete my unapproved translations of a document all at once.

[wmhn1872265132]

Can you explain this further? Generally, the pattern should be either:

1. Connect to Crowdin with PoEdit. Choose the po or xliff file to translate. Make changes, and save. Ipprove strings in the Crowdin interface. Or
2. Download the file from Crowdin. Open in PoEdit. Make changes, and save. Upload to Crowdin optionally approving all strings in the file.

Please explain more about updating local translations from a .pot file.

The interface has been translated as an example:

• Download nvda.po from Crowdin
• Translate
• NVDA has new translation entries updated
• At this point, nvda.pot can be downloaded from AppVeyor for import.

However, xliff has the following problems, making the above process unavailable:

1. When Poedit opens an xliff file, the Update from POT file command under Translation is unavailable.
2. AppVeyor does not have a valid translation template to import.

I agree this would complicate things. The source xliff files we upload to Crowdin does not contain any target tags at all. Are you saying that when you download the partially translated xliff, it already has target tags with the English pre-filled? Can you provide an example file?

Regarding the sample files, the user guide in Simplified Chinese can be downloaded from Crowdin and viewed in Poedit, please ignore the warning entries

Do you mean <target /> within the segment tag in the xliff file? Can you explain the impact of this further? Does PoEdit not treat this as untranslated the next time you open the file? Can you provide an example file?

We will of course continue to try and improve the workflow here where we can. We have no future plan to to allow translation of the raw markdown at this stage. We want to fully try and solve all issues so that files can be translated in a standard way using PoEdit.

The display of Poedit is normal, but there is a problem with the uploaded results. For details, please refer to
https://crowdin.com/project/nvda/activity-stream
Examples of errors in yesterday's Simplified Chinese translation

[michaelDCurran]

I'm not following why you need to manually download the pot file from appveyor and import into PoEdit.
If you download nvda.po from Crowdin in your language, translate and upload again, Crowdin will automatically merge in new changes to nvda.pot when they are uploaded to Crowdin by Appveyor. In other words, all you need to do is download, translate and upload. You should never have to touch the nvda.pot from Appveyor directly.
Can other translators for other languages please confirm this?

[wmhn1872265132]

This is mainly done to

1. Translate in advance and test in alpha version
2. If in the early translation stage, the file being translated is updated, there is no need to upload/download repeatedly. It can be updated locally and uploaded once after the translation is completed.

[seanbudd]

Translating alpha is not supported