Merge remote-tracking branch 'remotes/origin/master' into scons4.8.1to4.9.1

Author: dpy013

projectDocs/translating/crowdin.md

@@ -1,45 +1,91 @@
-# Translating using Crowdin
+# Translating with Crowdin
 
-Crowdin is used to translate the main NVDA interface and user documentation.
+Crowdin is used to manage the translations of the main NVDA interface and user documentation.
 NVDA's Crowdin project: <https://crowdin.com/project/nvda>.
 
-This document covers setting up a Crowdin account, connecting it with PoEdit, and translating the main interface and user documentation using Crowdin and PoEdit.
+This document covers setting up a Crowdin account, and translating the main interface and user documentation using either the Crowdin web interface or Poedit / nvdaL10nUtil.
 
-## Setup
-
-### Create Crowdin account
+## Creating a Crowdin account
 
 1. Create a [Crowdin account](https://accounts.crowdin.com/register?continue=%2Fproject%2Fnvda).
 1. Message the [translators mailing list](https://groups.io/g/nvda-translations) or <[email protected]> to request being added as a translator.
 Please include your Crowdin username and the languages you wish to translate.
 
-### Setup PoEdit
+## Translation workflows
+
+There are 2 common workflows for translating with Crowdin:
+
+1. Translating strings directly via Crowdin's web interface. Or
+1. Downloading a translation file from Crowdin, translating with Poedit, and uploading the file back to Crowdin.
+
+### Translating via Crowdin's web interface
+
+For instructions on how to translate strings using Crowdin's web interface, please read [Crowdin's documentation for translators](https://support.crowdin.com/for-translators/).
+
+Note: If you are a screen reader user, you may find Crowdin's web interface inefficient or impossible to use.
+Therefore you may choose to use the Poedit workflow instead.
+
+#### Translation Reviews / Approvals
+
+Due to accessibility issues and to be able to support the alternative workflow using Poedit, the translation approvals feature has been disabled in the NVDA project on Crowdin.
+This means that all new strings are essentially auto approved.
+However, to maintain quality control, only translators specifically added to the project can add or change strings.
+
+### Translating with Poedit
+
+Poedit is a desktop application which is commonly used to translate files.
+It is fairly accessible and is used by many blind and vision impaired translators.
+
+The workflow for translating with Poedit involves:
+1. Downloading the translation file using NVDA's l10n utility
+1. Opening the translation file in Poedit, translating one or more strings, and saving the file.
+1. Uploading the translation file back to Crowdin.
+
+Warning: Do not download / upload translation files via Crowdin's web interface, nor use Poedit's Crowdin cloud translation feature, as these methods have been found to corrupt xliff files.
+Please instead use NvDA's l10n utility for download and upload.
+NVDA's l10n utility will automatically use the appropriate Crowdin settings when downloading and uploading, and will detect and correct corruptions in xliff files.
+
+#### Setting up PoEdit
 
 It is recommended that you use the latest version of PoEdit and NVDA for translating.
-Alternatively, you can use the [Crowdin web interface](https://support.crowdin.com/online-editor/) directly.
-As PoEdit only supports viewing approved strings, large translator teams need to co-ordinate submitting unapproved strings to prevent conflicts.
-Using Crowdin's interface avoids this problem.
 
 PoEdit's homepage is: <http://www.poedit.net/>
 
 1. Download the latest Windows PoEdit version at <https://poedit.net/download>
 1. Install it by following the on-screen instructions, the default options should be sufficient.
 
-### Translation reviews
-Due to accessibility issues, for now translation approvals have been disabled on Crowdin.
-Any translation uploaded to Crowdin is automatically available in the project.
-However, joining the project as a translator is by invitation only.
+#### Locating the NVDA l10n utility
 
-## Translation workflows
+The NVDA l10n utility is required for safely and efficiently downloading and uploading translation files from / to Crowdin when translating with Poedit.
 
-There are 2 common workflows for translating with Crowdin:
+This utility is included with all versions of NVDA from 2025.1beta1 onwards.
 
-1. Translating strings directly via Crowdin's interface. Or
-1. Downloading from Crowdin, translating with Poedit and uploading again.
+* For installed copies of NVDA, its path is: `c:\Program Files (x86)\nvda\l10nUtil.exe`
+* For portable copies, it can be found as `l10nUtil.exe` in the root directory of the portable copy.
 
-## Translating using PoEdit
+#### Downloading po / xliff files with NVDA's l10n utility
 
-After opening a .po or .xliff file you will be placed on a list with all of the strings to translate.
+```sh
+l10nUtil.exe downloadTranslationFile <language> <crowdinFilePath> [<localFilePath>]
+```
+
+E.g.
+
+```sh
+l10nUtil.exe downloadTranslationFile fr nvda.po
+```
+The first time you will be asked for an authorization token.
+Please visit [your Crowdin settings API page](https://crowdin.com/settings#api-key) and create a Personal Access Token.
+Ensure that it has at least the translations scope.
+Then paste this into the user prompt.
+This will be saved in ~/.nvda_crowdin for future use.
+
+If your language team has more than one translator who may be downloading, translating and uploading at the same time, it is important that once you have downloaded the file, that you save a copy before you start translating with Poedit.
+This then allows you to provide l10nUtil with this original file when uploading, so that it can just upload only what has changed, which will avoid accidentally overriding another translator's work.
+
+#### Translating po / xliff files using Poedit
+
+After opening a .po or .xliff file you have previously downloaded with NVDA's l10n utility, you will be placed on a list with all of the strings to translate.
 
 You can read the status bar to see how many strings have already been translated, the number of untranslated messages, and how many are fuzzy.
 A fuzzy string is a message which has been automatically translated, thus it may be wrong.
@@ -51,7 +97,7 @@ NVDA will beep if you are on an untranslated or fuzzy message.
 If you are using a braille display you'll see a star sign in-front of the messages you have to translate.
 
 You may want to spell the original string to be aware of any punctuation mark, capital letters, etc.
-PoEdit has a keystroke you may press while on an original string, `alt+c`, that copies the original string to the edit field when pressed.
+To copy the original string into the "Translated text" control ready for further translation, you can press `control+b`.
 You may then replace it with your translation as normal.
 
 Press `control+s` at any moment to save your work.
@@ -62,32 +108,33 @@ NVDA provides additional shortcuts for PoEdit which are described in [the User G
 If you are unsure of the meaning of the original interface message, consult automatic comments (also called translator comments), by pressing `control+shift+a`.
 Some comments provide an example output message to help you understand what NVDA will say when speaking or brailling such messages.
 
-## Translating NVDA's interface
+#### Uploading po / xliff files with NvDA's l10n utility
+
+After translating the file with Poedit, upload the file back to Crowdin.
 
-* Download the po file for your language from  Crowdin using NVA's l10nUtil.exe:
 ```
-l10nUtil.exe downloadTranslationFile <language> <crowdinFilePath> [<localFilePath>]
+l10nUtil.exe uploadTranslationFile <language> <crowdinFilePath> [<localFilePath>]
 ```
 E.g.
 ```
-l10nUtil.exe downloadTranslationFile fr nvda.po
-```
-The first time you will be asked for an authorization token.
-Please visit [your Crowdin settings API page](https://crowdin.com/settings#api-key) and create a Personal Access Token.
-Ensure that it has at least the translations scope.
-Then paste this into the user prompt.
-This will be saved in ~/.nvda_crowdin for future use.
-* Open the xliff file in Poedit, translate, and save the file.
-* Upload the translated file using l10nUtil
-```
-l10nUtil.exe uploadTranslationFile <language> <crowdinFilePath> [<localFilePath>]
+l10nUtil.exe uploadTranslationFile fr nvda.po
 ```
+
+If you had previously saved a copy of the downloaded file before translation, then you will also want to include this in the command, so that l10nUtil only uploads the strings you have actually changed:
 E.g.
 ```
-l10nUtil.exe uploadTranslationFile fr nvda.po
+l10nUtil.exe uploadTranslationFile fr nvda.po --old nvda_old.po
 ```
+Where `nvda_old.po` was the saved copy.
+
+## Translating NVDA's interface
+
+* If translating via the Crowdin web interface, you can find these strings in the `NVDA interface messages` file.
+* If translating via Poedit, you can download it as `nvda.po` using NVDA's l10n utility, e.g.
 
-Alternatively, you can use the [Crowdin interface directly](https://support.crowdin.com/online-editor/).
+  ```sh
+  l10nUtil.exe downloadTranslationFile fr nvda.po
+  ```
 
 ### Messages with formatting strings
 
@@ -180,34 +227,10 @@ Documentation available for translation includes:
 * The NVDA user guide (userGuide.xliff)
 * The NVDA What's New document (changes.xliff)
 
-To translate any of these files:
-
-* Download the xliff file for your language from  Crowdin using NVA's l10nUtil.exe:
-```
-l10nUtil.exe downloadTranslationFile <language> <crowdinFilePath> [<localFilePath>]
-```
-E.g.
-```
-l10nUtil.exe downloadTranslationFile fr userGuide.xliff
-```
-The first time you will be asked for an authorization token.
-Please visit [your Crowdin settings API page](https://crowdin.com/settings#api-key) and create a Personal Access Token.
-Ensure that it has at least the translations scope.
-Then paste this into the user prompt.
-This will be saved in ~/.nvda_crowdin for future use.
-* Make a copy of the downloaded file.
-* Open the xliff file in Poedit, translate, and save the file.
-* Upload the translated file using l10nUtil
-```
-l10nUtil.exe uploadTranslationFile <language> <crowdinFilePath> [<localFilePath>] [--old <oldLocalFilepath>]
-```
-E.g.
-```
-l10nUtil.exe uploadTranslationFile fr userGuide.xliff --old userGuide_backup.xliff
-```
-This will only upload added / changed translations since you downloaded the file.
+To translate any of these files either:
 
-Alternatively, you can use the [Crowdin interface directly](https://support.crowdin.com/online-editor/).
+* locate the file in the Crowdin web interface and translate directly, or
+* Download the file using NVDA's l10n utility, open the file in Poedit, translate and save, then upload the file with NVDA's l10n utility.
 
 ### Translating markdown
 

source/_remoteClient/client.py

@@ -20,6 +20,7 @@
 from logHandler import log
 from gui.guiHelper import alwaysCallAfter
 from utils.security import isRunningOnSecureDesktop
+from gui.message import MessageDialog, DefaultButton, ReturnCode, DialogType
 import scriptHandler
 
 from . import configuration, cues, dialogs, serializer, server, urlHandler
@@ -120,7 +121,7 @@ def toggleMute(self):
 		"""
 		if not self.isConnected():
 			# Translators: Message shown when attempting to mute the remote computer when no session is connected.
-			ui.message(pgettext("remote", "Not connected"))
+			ui.delayedMessage(pgettext("remote", "Not connected"))
 			return
 		self.localMachine.isMuted = not self.localMachine.isMuted
 		self.menu.muteItem.Check(self.localMachine.isMuted)
@@ -129,7 +130,7 @@ def toggleMute(self):
 		# Translators: Displayed when unmuting speech and sounds from the remote computer
 		UNMUTE_MESSAGE = _("Unmuted remote")
 		status = MUTE_MESSAGE if self.localMachine.isMuted else UNMUTE_MESSAGE
-		ui.message(status)
+		ui.delayedMessage(status)
 
 	def pushClipboard(self):
 		"""Send local clipboard content to the remote computer.
@@ -140,19 +141,19 @@ def pushClipboard(self):
 		connector = self.followerTransport or self.leaderTransport
 		if not getattr(connector, "connected", False):
 			# Translators: Message shown when trying to send the clipboard to the remote computer while not connected.
-			ui.message(pgettext("remote", "Not connected"))
+			ui.delayedMessage(pgettext("remote", "Not connected"))
 			return
 		elif self.connectedClientsCount < 1:
 			# Translators: Reported when performing a Remote Access action, but there are no other computers in the channel.
-			ui.message(pgettext("remote", "No one else is connected"))
+			ui.delayedMessage(pgettext("remote", "No one else is connected"))
 			return
 		try:
 			connector.send(RemoteMessageType.SET_CLIPBOARD_TEXT, text=api.getClipData())
 			cues.clipboardPushed()
 		except (TypeError, OSError):
 			log.debug("Unable to push clipboard", exc_info=True)
 			# Translators: Message shown when clipboard content cannot be sent to the remote computer.
-			ui.message(pgettext("remote", "Unable to send clipboard"))
+			ui.delayedMessage(pgettext("remote", "Unable to send clipboard"))
 
 	def copyLink(self):
 		"""Copy connection URL to clipboard.
@@ -162,10 +163,12 @@ def copyLink(self):
 		session = self.leaderSession or self.followerSession
 		if session is None:
 			# Translators: Message shown when trying to copy the link to connect to the remote computer while not connected.
-			ui.message(pgettext("remote", "Not connected"))
+			ui.delayedMessage(pgettext("remote", "Not connected"))
 			return
 		url = session.getConnectionInfo().getURLToConnect()
 		api.copyToClip(str(url))
+		# Translators: A message indicating that a link has been copied to the clipboard.
+		ui.delayedMessage(_("Copied link"))
 
 	def sendSAS(self):
 		"""Send Secure Attention Sequence to remote computer.
@@ -191,6 +194,7 @@ def connect(self, connectionInfo: ConnectionInfo):
 		elif connectionInfo.mode == ConnectionMode.FOLLOWER:
 			self.connectAsFollower(connectionInfo)
 
+	@alwaysCallAfter
 	def disconnect(self):
 		"""Close all active connections and clean up resources.
 
@@ -199,6 +203,36 @@ def disconnect(self):
 		if self.leaderSession is None and self.followerSession is None:
 			log.debug("Disconnect called but no active sessions")
 			return
+
+		if (
+			self.followerSession is not None
+			and configuration.getRemoteConfig()["ui"]["confirmDisconnectAsFollower"]
+		):
+			if core._hasShutdownBeenTriggered:
+				log.info("NVDA is shutting down, skipping remote disconnect confirmation dialog.")
+			else:
+				confirmation_buttons = (
+					DefaultButton.YES,
+					DefaultButton.NO.value._replace(defaultFocus=True, fallbackAction=True),
+				)
+
+				dialog = MessageDialog(
+					parent=None,
+					# Translators: Title of the Remote Access disconnection confirmation dialog.
+					title=pgettext("remote", "Confirm Disconnection"),
+					message=pgettext(
+						"remote",
+						# Translators: Message shown when disconnecting from the remote computer.
+						"Are you sure you want to disconnect from the Remote Access session?",
+					),
+					dialogType=DialogType.WARNING,
+					buttons=confirmation_buttons,
+				)
+
+				if dialog.ShowModal() != ReturnCode.YES:
+					log.info("Remote disconnection cancelled by user.")
+					return
+
 		log.info("Disconnecting from remote session")
 		if self.localControlServer is not None:
 			self.localControlServer.close()

source/_remoteClient/cues.py

@@ -65,7 +65,7 @@ def _playCue(cueName: str) -> None:
 
 	# Show message if specified
 	if message := CUES[cueName].get("message"):
-		ui.message(message)
+		ui.delayedMessage(message)
 
 
 def connected():

source/config/configSpec.py

@@ -363,6 +363,7 @@
 		__many__ = string(default="")
 	[[ui]]
 		playSounds = boolean(default=True)
+		confirmDisconnectAsFollower = boolean(default=True)
 """
 
 #: The configuration specification

source/globalCommands.py

@@ -4911,8 +4911,6 @@ def script_pushClipboard(self, gesture: "inputCore.InputGesture"):
 	@gui.blockAction.when(gui.blockAction.Context.REMOTE_ACCESS_DISABLED)
 	def script_copyRemoteLink(self, gesture: "inputCore.InputGesture"):
 		_remoteClient._remoteClient.copyLink()
-		# Translators: A message indicating that a link has been copied to the clipboard.
-		ui.message(_("Copied link"))
 
 	@script(
 		category=SCRCAT_REMOTE,

source/gui/blockAction.py

@@ -11,15 +11,8 @@
 from functools import wraps
 import globalVars
 from typing import Any
-from speech.priorities import SpeechPriority
 import ui
 from utils.security import isLockScreenModeActive, isRunningOnSecureDesktop
-import core
-
-_DELAY_BEFORE_MESSAGE_MS = 1
-"""Duration in milliseconds for which to delay announcing that an action has been blocked, so that any UI changes don't interrupt it.
-1ms is a magic number. It can be increased if it is found to be too short, but it should be kept to a minimum.
-"""
 
 
 def _isModalMessageBoxActive() -> bool:
@@ -114,12 +107,7 @@ def funcWrapper(*args, **kwargs):
 					if context.callback is not None:
 						context.callback()
 					# We need to delay this message so that, if a UI change is triggered by the callback, the UI change doesn't interrupt it.
-					core.callLater(
-						_DELAY_BEFORE_MESSAGE_MS,
-						ui.message,
-						context.translatedMessage,
-						SpeechPriority.NOW,
-					)
+					ui.delayedMessage(context.translatedMessage)
 					return
 			return func(*args, **kwargs)