feat: use skipSyncUiDialogTranslation option for localization on simu…

…lators (#2276)

* feat: add skipSyncUiDialogTranslation for initializing simulator

* fix: avoid WDA shutdown when running mobile: configureLocalization script

ref: appium/appium#19440 (comment)

---------

Co-authored-by: Kazuaki Matsuo <fly.49.89.over@gmail.com>

docs/capabilities.md

@@ -89,6 +89,7 @@ Capability | Description
 |`appium:scaleFactor`|Simulator scale factor. This is useful to have if the default resolution of simulated device is greater than the actual display resolution. So you can scale the simulator to see the whole device screen without scrolling.|Acceptable values for simulators running Xcode SDK 8 and older are: `'1.0', '0.75', '0.5', '0.33' and '0.25'`, where '1.0' means 100% scale. For simulators running Xcode SDK 9 and above the value could be any valid positive float number. The capability must be of a string type.|
 |`appium:connectHardwareKeyboard`|Set this option to `true` in order to enable hardware keyboard in Simulator. The preference works only when XCUITest driver launches a simulator instance with this value. It is set to `false` by default, because this helps to workaround some XCTest bugs. `connectHardwareKeyboard: true` makes `forceSimulatorSoftwareKeyboardPresence: false` if no explicit value is set for `forceSimulatorSoftwareKeyboardPresence` capability since Appium 1.22.0. |`true` or `false`|
 |`appium:forceSimulatorSoftwareKeyboardPresence`|Set this option to `true` in order to turn software keyboard on and turn hardware keyboard off in Simulator since Appium 1.22.0. This option helps to avoid `Keyboard is not present` error. It is set to `true` by default. XCUITest driver respects preset simulator software/hardware keyboard preference when this value is `false`, so `connectHardwareKeyboard: false` and `forceSimulatorSoftwareKeyboardPresence: false` means for XCUITest driver to keep the current Simulator keyboard preferences. This option has priority over `connectHardwareKeyboard`. |`true` or `false`|
+|`appium:skipSyncUiDialogTranslation`|Set this option to `true` in order to skip synchronizing UI dialogs translation. While this option might leave some system UI alerts untranslated, it helps to avoid unexpected side effects (see https://github.com/appium/appium/issues/19440 for more details). It is set to `false` by default. |`true` or `false`|
 | **Deprecated** `appium:calendarAccessAuthorized`|This capability is obsolete. Please use `appium:permissions` one instead with the `calendar` key.|`true` or `false`|
 |`appium:isHeadless`|Set this capability to `true` if automated tests are running on Simulator and the device display is not needed to be visible. This only has an effect since Xcode9 and only for simulators. All running instances of Simulator UI are going to be automatically terminated if headless test is started. `false` is the default value.|e.g., `true`|
 |`appium:simulatorWindowCenter`|Allows to explicitly set the coordinates of Simulator window center for Xcode9+ SDK. This capability only has an effect if Simulator window has not been opened yet for the current session before it started.|e.g. `{-100.0,100.0}` or `{500,500}`, spaces are not allowed|

docs/execute-methods.md

@@ -682,8 +682,9 @@ remotePath | string | yes | Same value as for `mobile: deleteFile` except of the
 Change localization settings on the currently booted Simulator.
 The changed settings are only applied for the *newly started* applications/activities.
 Currently running applications will stay unchanged. This means, for example, that the keyboard
-should be hidden and shown again in order to observe the changed layout, and curresponding
+should be hidden and shown again in order to observe the changed layout, and corresponding
 apps must be restarted in order to observe their interface using the newly set locale/language.
+Also this method might leave some system UI alerts untranslated.
 Be careful while setting the actual arguments since their actual values are not strictly checked.
 This could lead to an unexpected behavior if an incorrect/unsupported language or locale abbreviation is provided.
 

lib/commands/localization.js

@@ -22,9 +22,14 @@ export default {
   async mobileConfigureLocalization(keyboard, language, locale) {
     assertSimulator(this);
 
+    const localizationOptions = {locale, keyboard};
+    if (language) {
+      // Assign skipSyncUiDialogTranslation: true option in order to avoid shutting down the WDA session
+      localizationOptions.language = Object.assign(language, {skipSyncUiDialogTranslation: true});
+    }
     return /** @type {boolean} */ (
       // @ts-expect-error - do not assign arbitrary properties to `this.opts`
-      await this.opts.device.configureLocalization({language, locale, keyboard})
+      await this.opts.device.configureLocalization(localizationOptions)
     );
   },
 };

lib/desired-caps.js

@@ -352,6 +352,9 @@ const desiredCapConstraints = /** @type {const} */ ({
   skipTriggerInputEventAfterSendkeys: {
     isBoolean: true,
   },
+  skipSyncUiDialogTranslation: {
+    isBoolean: true,
+  },
 });
 
 export {desiredCapConstraints, PLATFORM_NAME_IOS, PLATFORM_NAME_TVOS};

lib/simulator-management.js

@@ -307,10 +307,10 @@ async function setSafariPrefs(sim, opts = {}) {
  * @returns {Promise<boolean>} True if preferences were changed
  */
 async function setLocalizationPrefs(sim, opts = {}) {
-  const {language, locale, calendarFormat} = opts;
+  const {language, locale, calendarFormat, skipSyncUiDialogTranslation} = opts;
   const l10nConfig = {};
   if (language) {
-    l10nConfig.language = {name: language};
+    l10nConfig.language = {name: language, skipSyncUiDialogTranslation };
   }
   if (locale) {
     l10nConfig.locale = {name: locale};