Remove outdated translated developerGuide, or move to Crowdin (was: remove outdated files)

[CyrilleB79]

Issue opened after discussion in #13119 (comment) and #13119 (comment) regarding translated developer's guides.

Steps to reproduce:

List the file names in all the language subfolders of user_docs folder.

Actual behavior:

The most common (and expected files are: changes.html/.t2t, keyCommands.html/.t2t, styles.css, userGuide.html/.t2t.

Still remaining - to be either removed or moved to crowdin:
developerGuide.html/.md in de and pt_BR folders
Last commits: Fri Aug 3 2012 (de) and Tue Aug 9 2011 (pt_BR)

Removed:

1. locale.t2tconf files are present for ar, fa and he languages to manage right to left text direction and arabic numbers.
2. locale.t2tconf in ca (Catalan) folder
   Last commit: Wed Aug 20 21:42:40 2014 +0100
3. hu\chapter0.t2tinc
   Last commit: Wed Mar 20 2013
4. th\key commands.txt
   Last commit: Sun Dec 14 2008

Expected behavior:

The files listed in 1. and 2. are expected. The files listed in the other points were not expected. The question arises of removing them for the following reasons:

• Files listed in 4. and 6. are very old and it is expected that such files are updated regularly (dev guide and key commands). It should be investigated if these files are still of any use for their respective community (de, pt_BR and th) since they are probably far from up-to-date.
  Note that "th/key commands.txt" is not even opened when setting NVDA in Thai and clicking the "Key commands" item in the "Help" menu; English key commands html file is opened instead. Either this file should be renamed "keyCommands.txt" to be accessed through the menu or some dead code could probably be removed from getDocFilePath in file documentationUtils.py.
• ca\locale.t2tconf (3.): I wonder why Catalan needs a specific processing with respect to other latin languages. Either other languages should benefit from what has been done for Catalan, or this specific processing for Catalan is not needed anymore; to be investigated.
• Point 3.: hu user guide adds additional specific content. It should be stated if local teams are still allowed to include such specific content with respect to the standard user guidd. This decision can be made when the new translation framework is set up.

System configuration

NVDA installed/portable/running from source:

N/A

NVDA version:

2021.3.1

Windows version:

N/A

Name and version of other software in use when reproducing the issue:

N/A

Other information about your system:

N/A

Other questions

Does the issue still occur after restarting your computer?

N/A

Have you tried any other versions of NVDA? If so, please report their behaviors.

N/A

If NVDA add-ons are disabled, is your problem still occurring?

N/A

Does the issue still occur after you run the COM Registration Fixing Tool in NVDA's tools menu?

N/A

Cc @bdorer, @mhameed who have committed on these files.
Also wanted to cc David Parduhn, Rene Linke and Peter Vagne, but I do not have their GitHub user name (if they have one).

[tiago-casal]

Hello! The pt_BR/developerGuide.t2t translation is being updated, but it will take a while to get ready.

[CyrilleB79]

Hello! The pt_BR/developerGuide.t2t translation is being updated, but it will take a while to get ready.

Thanks for your feedback @tiago-casal. Could you tell a bit more on the pt_BR dev guide:

• Who is translating this doc? Yourself? With others?
• Is there a more recent version somewhere else than the one bundled in NVDA?
• Is the pt_BR dev guide used in the Brazilian dev community or in the Portuguese one? If yes, which version?
• How do translator(s) manage the updates in the source (English) dev guide? Is the translator translating a specific commit of this doc?

I think all this information is needed to show that this translation is a living project.

[tiago-casal]

Hello! The pt_BR/developerGuide.t2t translation is being updated, but it will take a while to get ready.

Thanks for your feedback @tiago-casal. Could you tell a bit more on the pt_BR dev guide:

• Who is translating this doc? Yourself? With others?
• Is there a more recent version somewhere else than the one bundled in NVDA?
• Is the pt_BR dev guide used in the Brazilian dev community or in the Portuguese one? If yes, which version?
• How do translator(s) manage the updates in the source (English) dev guide? Is the translator translating a specific commit of this doc?

I think all this information is needed to show that this translation is a living project.

Hello @CyrilleB79!

I'm part of the NVDA Brazilian Portuguese translation team, I'm working on updating the developerGuide.t2t file; in the team, everyone contributes to the work of others, whether translating or revising; everything that is documentation is interesting to be translated into the native language, there are users who want to start contributing and only speak the native language, translated document is the first step.

The update is currently being based on the English file that is in the sources of NVDA 2021.3.1; this probably won't end before the release of NVDA 2022.1, so when beta versions of NVDA 2022.1 are released we will use the latest version file.

It's difficult to identify the changes due to the lack of the same mechanism (scripts) used to create a differences file in the translation repository, I ended up doing it manually (I have a Linux distribution installed on my PC and I use diff).

When it was finished, I would send a pull request attaching the file for replacement in the sources, now that the outdated files are being deleted, I'll need to find a place to make them available, as it doesn't come in the NVDA installer; a site suggestion that could be thought of so that such files are available even without coming in the installer, would be at (what do you think of this?): https://www.nvaccess.org/files/nvda/releases/stable/documentation/

The NVDA European Portuguese translation team also has a translated version of developerGuide.t2t, which is in the translation repository, it's also outdated: https://subversion.assembla.com/svn/screenReaderTranslations/pt_PT/developerGuide.t2t

Thankful for your attention!

[josephsl]

Hi, the thing is, developer guide is not really meant to be translated, although I understand the need for a translated version of this document for language communities. I propose that language communities host translated versions of developer documentation on their websites or a place where people speaking the said language can gather. Thanks.

[tiago-casal]

Hi, the thing is, developer guide is not really meant to be translated, although I understand the need for a translated version of this document for language communities. I propose that language communities host translated versions of developer documentation on their websites or a place where people speaking the said language can gather. Thanks.

Thanks @josephsl! I understand, however, the lack of a centralized place for making materials available from NVDA with optional translation, makes things fragmented, there are teams that don't even have their own website, making it available on the NVDA Community Add-ons website I don't know if it would be an appropriate alternative, this would unstandardize the website.

[josephsl]

Hi, until recently the community add-ons website was home to add-on development guide, but the guide was moved to GitHub so it can be kept updated as NVDA development progresses. As a compromise, I think it would be best to revive the language portal page from NV Access site where we have links to language communities. Thanks.

[tiago-casal]

Hi, until recently the community add-ons website was home to add-on development guide, but the guide was moved to GitHub so it can be kept updated as NVDA development progresses. As a compromise, I think it would be best to revive the language portal page from NV Access site where we have links to language communities. Thanks.

Hi, it would really help if the NVDA Add-on Development Guide were restored on the NVDA Community Add-ons website, and additionally, the developerGuide.t2t in question was included, so it would be much more practical to translate both when each team wants. Grateful!

[josephsl]

Hi, as for restoring add-on dev guide on community add-ons website, I don’t think so for now, both for short-term and long-term reasons. In the short-term, the dev guide is really meant to serve as a wiki document so it can keep up with latest changes to NVDA, and I don’t think some GitHub syntax would work well on Ikiwiki infrastructure. In the long-term, the community add-ons website is slated to receive a complete makeover, and I don’t think the dev guide would survive it. There was (and I think still is) a philosophical debate as to who should take more responsibility of the community add-ons website – the add-ons community, or the translations community, and I fall into the former. Part of the reason why the add-on dev guide was hosted on the community add-ons website until recently is due to the fact that the add-ons website was initially maintained by translators, and as part of a follow-up to #3208, it was pointed out that this tight integration between the add-ons community and translators (in terms of the infrastructure) is not good for the long-term maintenance and viability of the community add-ons website as a whole. While I understand the need to host translated versions of add-on and NVDA dev guides on community add-ons website, these guides are not intended to be translated in the first place and were stored on that site as a temporary measure until we found a better place to host them. Therefore, as the original author of add-on development guide and at one point the visionary of community add-ons website maintenance, I am afraid that this suggestion cannot be honored. This does not mean that the door is closed to this suggestion forever – the people to convince would be NV Access folks as they plan to coordinate add-on release process and related things in the future. Thanks.

[CyrilleB79]

When it was finished, I would send a pull request attaching the file for replacement in the sources, now that the outdated files are being deleted, I'll need to find a place to make them available, as it doesn't come in the NVDA installer;

Please note that the pt_BR dev guide is not deleted from NVDA's codebase for now. In this PR, I was asking for unmaintained files. However since you explain that there is an active work on this guide's translation, I do not consider it anymore as an unmaintained file.

Then if maintained translated developer guide should be removed from NVDA's core and put elsewhere will be the decision of NVAccess at the end. I suggest not to do anything on this point before they decide something; maybe this decision will also be part of the new translation framework.

The NVDA European Portuguese translation team also has a translated version of developerGuide.t2t, which is in the translation repository, it's also outdated: https://subversion.assembla.com/svn/screenReaderTranslations/pt_PT/developerGuide.t2t

Thanks for the information. I did not know of it.

Clearly there should be a clarification on if, where and how dev guides (NVDA and add-on) should be translated. However it should not be discussed in this little issue IMO.
More specifically, let's stop discussing add-on dev guide translation here since it is not the place at all.
Thanks.

[tiago-casal]

Please note that the pt_BR dev guide is not deleted from NVDA's codebase for now. In this PR, I was asking for unmaintained files. However since you explain that there is an active work on this guide's translation, I do not consider it anymore as an unmaintained file.

Thank you very much!

[seanbudd]

Note that now locale.t2tconf is supported and expected, these files should no longer be removed (#8856 #14546)

[seanbudd]

user_docs\hu\chapter0.t2tinc is a dependency of hungarian userGuide so it should not be removed either, instead migrated into the userGuide file properly

[seanbudd]

user_docs\hu\chapter0.t2tinc and the developer guides still remain to be considered removed

[seanbudd]

user_docs\hu\chapter0.t2tinc will be removed when we migrate from t2t to markdown as a source of truth. it is currently bundled/injected into the markdown file user_docs\hu\userGuide.md automatically.

So the only remaining question is whether we include the developerGuide optionally in the new translation system, or remove them

[Adriani90]

If the developer guide should ideally be translated, I would post a message to the translations mailing list and ask if people intend to work on it. Maybe explaining also how to add the developer guide to the respective language. I feel like many translators are even not really aware that this is possible and how. If there is no positive resonance about this, then I agree the files can be removed.

[seanbudd]

@Adriani90 I've posted to the translators and add-on mailing lists:

• https://nvda-addons.groups.io/g/nvda-addons/topic/translating_the_developer/103733745?p=,,,20,0,0,0::recentpostdate/sticky,,,20,2,0,103733745,previd%3D1705296274851147414,nextid%3D1704162361968504116&previd=1705296274851147414&nextid=1704162361968504116
• https://groups.io/g/nvda-translations/topic/translating_the_developer/103733682?p=,,,20,0,0,0::recentpostdate/sticky,,,20,2,0,103733682,previd%3D1705296052188349177,nextid%3D1702863265727456521&previd=1705296052188349177&nextid=1702863265727456521

[seanbudd]

Given that the user guide and changes document will require a lot of work from translators in the 2024.1 release, I don't think we will consider including the dev guide until 2024.2

[Nael-Sayegh]

Hello @CyrilleB79 ,
Is this ticket still active?
I could take care of cleaning the files based on your various comments.

[CyrilleB79]

@Nael-Sayegh could you summarize what needs to be cleaned?
A quick look at the discussion let me think that only the dev guide topic is still relevant.

But according to #13333 (comment) and the linked discussions, it is not sure that the dev guide will be removed.

[Nael-Sayegh]

@CyrilleB79 Based on this response from @seanbudd in this comment, I understood that there was consideration of deleting the developer guide. If that's not the case, I conclude that there are no files left to delete. But then, why does this issue remain open?

[CyrilleB79]

But in #13333 (comment) that is more recent, it seems that inclusion of the dev guide may be considered for 2024.2, or maybe 2024.3 actually since the transition to the new framework for the Change log and User Guide have been shifted to 2024.2.

But the decision to include it or not does not seem to be definitively made. Thus I'd suggest to revisit this issue and decide for the dev guide after the Change log and the User Guide are migrated to CrowdIn.

[seanbudd]

In #16627 (comment) @Adriani90 wrote:

If this is part of the developer guide, then in my view it becomes even more relevant to deploy the developer guide via SVN or Crowdin for tranlsation to every language, so #13333 should definitely not cause the developer guide to be removed.

To be clear, this issue is about determining if the devGuide should be translatable. If not, the outdated german and portugese developer guides are under consideration for removal, not the base devGuide.
I'm not sure if #16627 should affect this decision.
The alternative to #16627 is to migrate the content into a "translating guide" or keep it "projectDocs" like other documentation.
It is unlikely "projectDocs" will be translated any time soon, however a translating guide could be translated independently.

For translators, being able to understand English is a must.
While I understand that translating the guides for translating may make translating easier, I don't see it as impacting this issue.
I don't see how translating the translating guides has a higher impact than translating the developer Guide as-is.
Add-on developers do not need to understand english, so lowering the barrier for them is of higher importance than translators, which need to understand english.