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.