Update devGuide for translating symbols, gestures, character descriptions

[seanbudd]

Link to issue number:

Closes #16372

Summary of the issue:

Dev guide is out of date on translating symbols, character descriptions and gestures. It refers to the SVN process which is now deprecated. We only accept changes to these files via PR now.

Description of user facing changes

Update dev guide to refer to opening a PR rather than using SVN.

[CyrilleB79]

I'd move this paragraph at the end. Indeed the sentence before announces the two next paragraphs.

[CyrilleB79]

Please communicate with translators mailing list before merging. You may have valuable feedback.

Regarding my general personal feedback (already done in the past when transition to Crowdin was discussed):

1. I agree that updating local gestures.ini through GitHub makes sense: writing this file requires to know NVDA's code, namely the classes where original gestures are defined. And I make the assumption that translators that have modified this file recently also have a certain knowledge of NVDA's code. Moreover, if a translator needs the help from an NVDA code contributor to identify the appropriate NVDA class, to write an updated gesture file or to make a PR, this is acceptable since gesture files are not modified so frequently and are modified only in a few languages.

2. I agree that modifying the character file can be done through GitHub. These files are almost never modified once created. If a translator wants to add a character description file for a new language, a code contributor can help him/her or do it for him/her since this occurs very rarely.

3. Regarding the symbol file, I am not so convinced that GitHub is suitable, even if I have no other option to suggest. The symbol file is updated more frequently than the two other files and for all languages. I expect that with the switch to GitHub, more languages local files will not keep up to date with the English file. The question is "When symbols are added or modified in the English file, who will make a PR to update language xy"? Translators, NVDA code contributors, NV Access? We cannot expect every translator to install NVDA source environment (NVDA Git local repository, Visual Studio, etc.). The corresponding section of the dev guide links to https://github.com/nvaccess/nvda/blob/master/projectDocs/dev/contributing.md, which is very general. If I was a non-dev translator, I would not know where I should begin from to update a symbol file. Also in SVN translators were notified of changes in the English symbol file. Now, for each release, they would need to do a git diff on this file to see what has changed. Or could NV Access send this information on the translators mailing list when NVDA enters the beta phase as well as each time the file is updated during the beta phase?

Please communicate with translators mailing list before merging. You may have valuable feedback.

Regarding my personal feedback (already done in the past when transition to Crowdin was discussed):

1. I agree that updating local gestures.ini through GitHub makes sense: writing this file requires to know NVDA's code, namely the classes where original gestures are defined. And I make the assumption that translators that have modified this file recently also have a certain knowledge of NVDA's code. Moreover, if a translator needs the help from an NVDA code contributor to identify the appropriate NVDA class, to write an updated gesture file or to make a PR, this is acceptable since gesture files are not modified so frequently and are modified only in a few languages.

2. I agree that modifying the character file can be done through GitHub. These files are almost never modified once created. If a translator wants to add a character description file for a new language, a code contributor can help him/her or do it for him/her since this occurs very rarely.

3. Regarding the symbol file, I am not so convinced that GitHub is suitable, even if I have no other option to suggest. The symbol file is updated more frequently than the two other files and for all languages. I expect that with the switch to GitHub, more languages local files will not keep up to date with the English file. The question is "When symbols are added or modified in the English file, who will make a PR to update language xy"? Translators, NVDA code contributors, NV Access? We cannot expect every translator to install NVDA source environment (NVDA Git local repository, Visual Studio, etc.).

[zstanecic]

Hi there!
I agree here with @CyrilleB79
Regarding the translation of the symbols file, I disagree it moving to github.
We don't know, and will not know, what changed via any means of diffs.
Translator is often not a programmer, and translators should have a straightforward way to update symbols.

[michaelDCurran]

Also in SVN translators were notified of changes in the English symbol file. Can you explain this further. How exactly were translators notified about this file? Do you mean just reading svn log, or were there specific notifications sent when the english symbols.dic was updated? I agree it is overkill to expect translators to have to create an entire NVDA source environment for symbols. But until we have a suitable alternative, this is how it is.

[CyrilleB79]

Also in SVN translators were notified of changes in the English symbol file. Can you explain this further. How exactly were translators notified about this file? Do you mean just reading svn log, or were there specific notifications sent when the english symbols.dic was updated?

In SVN, we have:

• An e-mail sent when any new translation is merged to SVN indicating which file is modified, including symbol file. In Crowdin we have no e-mail notification anymore, but we still can look at the % translated in Crowdin interface (exception made of the doc strings that are the same as English, but it's not the topic here.
• Each diff on the symbol file listed in SRT\fr\symbols-newRevisions, which is quite easy for the user to just focus on new content to translate, and also to keep track of what he/she has already translated and which modification still remains to translate.

I agree it is overkill to expect translators to have to create an entire NVDA source environment for symbols. But until we have a suitable alternative, this is how it is.

[CyrilleB79]

I agree it is overkill to expect translators to have to create an entire NVDA source environment for symbols. But until we have a suitable alternative, this is how it is.

I am not satisfied with this answer. I have not answered the poll regarding the technical documentation of NVDA. But if this PR is merged as is, I will answer it if it is still available, with a negative feedback.

The problem is that the majority of translators are not developers. Thus the translator should be able to read documentation to provide their translations without having to deal with a heavy developer process/environment.

Cc @gerald-hartig for opinion

[LeonarddeR]

I'm tempted to agree with @CyrilleB79 here. I"m worried that for many translators, switching from SVN to GIT will be overly complex.

[gerald-hartig]

@CyrilleB79 @LeonarddeR In your opinion, can we address the UX issues for the translators with quality of life improvements such as:

• Implement a process to automatically notify the translators mailing list whenever symbols.dic is modified in the main branch.
• Provide clear, step-by-step instructions targeting a non-developer audience, possibly in a dedicated section in the developer guide, that provides the minimum required environment.
• Gather feedback & iterate, and if GitHub is not the optimal long-term solution for managing symbols.dic, explore an alternative, more translator-friendly option that can be integrated with the existing GitHub workflow.

The documentation needs to be accurate and reflect the current process. Delaying this update hinders contributors and creates confusion. In my mind this is key, and then fixing the issues is then the next step.

[CyrilleB79]

@gerald-hartig, I agree that the current situation should be progressed.

Regarding your proposals:

• Implement a process to automatically notify the translators mailing list whenever symbols.dic is modified in the main branch.

That's already better than what is existing today (i.e. no information at all). Though, this proposal is not so useful as the old SVN framework.
In SVN, the current state of translation was followed for each language. That is, looking in a language's subfolders, a translator could know what had already been translated and what remains to be translated. E.g. the symbol folder contains n=4 subfolders indicate that there is (n-1) = 3 translation jobs remaining. A translator could translate half of the content (e.g. 2 out of 3 jobs), deleting the 2 corresponding subfolders, and keep other content to translate for later.
In today's proposal translators will have to manually take not or archive the received messages to know what has already been translated and what still needs to be.

Though regarding SVN subfolders, there were much less symbol updates than User Guide or Change log updates, so maybe it's not so disturbing?

• Provide clear, step-by-step instructions targeting a non-developer audience, possibly in a dedicated section in the developer guide, that provides the minimum required environment.

Yes, if all the information is detailed and gathered at the same place, it would be very useful.

Not only the "how" should be documented (file formats, dev translation ), but also the "when":
Before, users could translate from beta branching until the end of translation freeze. Now, translators could technically begin to submit work during alpha stage. It should be clarified, for example, if translation PRs will be accepted during alpha stage or not, or if they can be done during alpha stage but not recommended...

• Gather feedback & iterate, and if GitHub is not the optimal long-term solution for managing symbols.dic, explore an alternative, more translator-friendly option that can be integrated with the existing GitHub workflow.

Yes. That's the most important thing. NV Access must remain very attentive to user feedback on the translators mailing list.

The documentation needs to be accurate and reflect the current process. Delaying this update hinders contributors and creates confusion. In my mind this is key, and then fixing the issues is then the next step.

I understand and agree with you. Do not hesitate to communicate these evolutions on the mailing list.