[1812] Handover Translations

Author: Rixxan

EDMC.py

@@ -26,7 +26,6 @@
 
 if TYPE_CHECKING:
     from logging import TRACE  # type: ignore # noqa: F401 # needed to make mypy happy
-    def _(x: str): return x
 
 edmclogger.set_channels_loglevel(logging.INFO)
 
@@ -35,7 +34,7 @@ def _(x: str): return x
 import commodity
 import companion
 import edshipyard
-import l10n
+from l10n import translations as tr
 import loadout
 import outfitting
 import shipyard
@@ -66,7 +65,7 @@ def log_locale(prefix: str) -> None:
                  )
 
 
-l10n.Translations.install_dummy()
+tr.install_dummy()
 
 SERVER_RETRY = 5  # retry pause for Companion servers [s]
 EXIT_SUCCESS, EXIT_SERVER, EXIT_CREDENTIALS, EXIT_VERIFICATION, EXIT_LAGGING, EXIT_SYS_ERR, EXIT_ARGS, \
@@ -164,7 +163,7 @@ def main():  # noqa: C901, CCR001
             newversion: EDMCVersion | None = updater.check_appcast()
             if newversion:
                 # LANG: Update Available Text
-                newverstr: str = _("{NEWVER} is available").format(NEWVER=newversion.title)
+                newverstr: str = tr.tl("{NEWVER} is available").format(NEWVER=newversion.title)
                 print(f'{appversion()} ({newverstr})')
             else:
                 print(appversion())

EDMarketConnector.py

@@ -37,12 +37,11 @@
 from edmc_data import companion_category_map as category_map
 from EDMCLogging import get_main_logger
 from monitor import monitor
+from l10n import translations as tr
 
 logger = get_main_logger()
 
 if TYPE_CHECKING:
-    def _(x: str): return x
-
     UserDict = collections.UserDict[str, Any]  # indicate to our type checkers what this generic class holds normally
 else:
     UserDict = collections.UserDict  # Otherwise simply use the actual class
@@ -224,7 +223,7 @@ def __init__(self, *args) -> None:
         self.args = args
         if not args:
             # LANG: Frontier CAPI didn't respond
-            self.args = (_("Error: Frontier CAPI didn't respond"),)
+            self.args = (tr.tl("Error: Frontier CAPI didn't respond"),)
 
 
 class ServerConnectionError(ServerError):
@@ -243,7 +242,7 @@ def __init__(self, *args) -> None:
         self.args = args
         if not args:
             # LANG: Frontier CAPI data doesn't agree with latest Journal game location
-            self.args = (_('Error: Frontier server is lagging'),)
+            self.args = (tr.tl('Error: Frontier server is lagging'),)
 
 
 class NoMonitorStation(Exception):
@@ -259,7 +258,7 @@ def __init__(self, *args) -> None:
         self.args = args
         if not args:
             # LANG: Commander is docked at an EDO settlement, got out and back in, we forgot the station
-            self.args = (_("Docked but unknown station: EDO Settlement?"),)
+            self.args = (tr.tl("Docked but unknown station: EDO Settlement?"),)
 
 
 class CredentialsError(Exception):
@@ -269,7 +268,7 @@ def __init__(self, *args) -> None:
         self.args = args
         if not args:
             # LANG: Generic "something went wrong with Frontier Auth" error
-            self.args = (_('Error: Invalid Credentials'),)
+            self.args = (tr.tl('Error: Invalid Credentials'),)
 
 
 class CredentialsRequireRefresh(Exception):
@@ -294,7 +293,7 @@ def __init__(self, *args) -> None:
         self.args = args
         if not args:
             # LANG: Frontier CAPI authorisation not for currently game-active commander
-            self.args = (_('Error: Wrong Cmdr'),)
+            self.args = (tr.tl('Error: Wrong Cmdr'),)
 
 
 class Auth:
@@ -429,7 +428,7 @@ def authorize(self, payload: str) -> str:  # noqa: CCR001
                 '<unknown error>'
             )
             # LANG: Generic error prefix - following text is from Frontier auth service
-            raise CredentialsError(f'{_("Error")}: {error!r}')
+            raise CredentialsError(f'{tr.tl("Error")}: {error!r}')
 
         r = None
         try:
@@ -472,18 +471,18 @@ def authorize(self, payload: str) -> str:  # noqa: CCR001
                 if (usr := data_decode.get('usr')) is None:
                     logger.error('No "usr" in /decode data')
                     # LANG: Frontier auth, no 'usr' section in returned data
-                    raise CredentialsError(_("Error: Couldn't check token customer_id"))
+                    raise CredentialsError(tr.tl("Error: Couldn't check token customer_id"))
 
                 if (customer_id := usr.get('customer_id')) is None:
                     logger.error('No "usr"->"customer_id" in /decode data')
                     # LANG: Frontier auth, no 'customer_id' in 'usr' section in returned data
-                    raise CredentialsError(_("Error: Couldn't check token customer_id"))
+                    raise CredentialsError(tr.tl("Error: Couldn't check token customer_id"))
 
                 # All 'FID' seen in Journals so far have been 'F<id>'
                 # Frontier, Steam and Epic
                 if f'F{customer_id}' != monitor.state.get('FID'):
                     # LANG: Frontier auth customer_id doesn't match game session FID
-                    raise CredentialsError(_("Error: customer_id doesn't match!"))
+                    raise CredentialsError(tr.tl("Error: customer_id doesn't match!"))
 
                 logger.info(f'Frontier CAPI Auth: New token for \"{self.cmdr}\"')
                 cmdrs = config.get_list('cmdrs', default=[])
@@ -505,7 +504,7 @@ def authorize(self, payload: str) -> str:  # noqa: CCR001
                 self.dump(r)
 
             # LANG: Failed to get Access Token from Frontier Auth service
-            raise CredentialsError(_('Error: unable to get token')) from e
+            raise CredentialsError(tr.tl('Error: unable to get token')) from e
 
         logger.error(f"Frontier CAPI Auth: Can't get token for \"{self.cmdr}\"")
         self.dump(r)
@@ -514,7 +513,7 @@ def authorize(self, payload: str) -> str:  # noqa: CCR001
             '<unknown error>'
         )
         # LANG: Generic error prefix - following text is from Frontier auth service
-        raise CredentialsError(f'{_("Error")}: {error!r}')
+        raise CredentialsError(f'{tr.tl("Error")}: {error!r}')
 
     @staticmethod
     def invalidate(cmdr: str | None) -> None:
@@ -841,7 +840,7 @@ def capi_single_query(
             except Exception as e:
                 logger.debug('Attempting GET', exc_info=e)
                 # LANG: Frontier CAPI data retrieval failed
-                raise ServerError(f'{_("Frontier CAPI query failure")}: {capi_endpoint}') from e
+                raise ServerError(f'{tr.tl("Frontier CAPI query failure")}: {capi_endpoint}') from e
 
             if capi_endpoint == self.FRONTIER_CAPI_PATH_PROFILE and 'commander' not in capi_data:
                 logger.error('No commander in returned data')
@@ -874,7 +873,7 @@ def handle_http_error(response: requests.Response, endpoint: str):
             if response.status_code == 418:
                 # "I'm a teapot" - used to signal maintenance
                 # LANG: Frontier CAPI returned 418, meaning down for maintenance
-                raise ServerError(_("Frontier CAPI down for maintenance"))
+                raise ServerError(tr.tl("Frontier CAPI down for maintenance"))
 
             logger.exception('Frontier CAPI: Misc. Error')
             raise ServerError('Frontier CAPI: Misc. Error')

companion.py

@@ -13,17 +13,13 @@
 from enum import Enum
 from os import getpid as os_getpid
 from tkinter import ttk
-from typing import TYPE_CHECKING, Callable
-
+from typing import Callable
+from l10n import translations as tr
 from config import config
 from EDMCLogging import get_main_logger
 
 logger = get_main_logger()
 
-if TYPE_CHECKING:  # pragma: no cover
-    def _(x: str) -> str:
-        return x
-
 
 class JournalLockResult(Enum):
     """Enumeration of possible outcomes of trying to lock the Journal Directory."""
@@ -212,7 +208,7 @@ def __init__(self, parent: tk.Tk, callback: Callable) -> None:
             self.parent = parent
             self.callback = callback
             # LANG: Title text on popup when Journal directory already locked
-            self.title(_('Journal directory already locked'))
+            self.title(tr.tl('Journal directory already locked'))
 
             # remove decoration
             if sys.platform == 'win32':
@@ -225,16 +221,17 @@ def __init__(self, parent: tk.Tk, callback: Callable) -> None:
 
             self.blurb = tk.Label(frame)
             # LANG: Text for when newly selected Journal directory is already locked
-            self.blurb['text'] = _("The new Journal Directory location is already locked.{CR}"
-                                   "You can either attempt to resolve this and then Retry, or choose to Ignore this.")
+            self.blurb['text'] = tr.tl("The new Journal Directory location is already locked.{CR}"
+                                       "You can either attempt to resolve this and then Retry, "
+                                       "or choose to Ignore this.")
             self.blurb.grid(row=1, column=0, columnspan=2, sticky=tk.NSEW)
 
             # LANG: Generic 'Retry' button label
-            self.retry_button = ttk.Button(frame, text=_('Retry'), command=self.retry)
+            self.retry_button = ttk.Button(frame, text=tr.tl('Retry'), command=self.retry)
             self.retry_button.grid(row=2, column=0, sticky=tk.EW)
 
             # LANG: Generic 'Ignore' button label
-            self.ignore_button = ttk.Button(frame, text=_('Ignore'), command=self.ignore)
+            self.ignore_button = ttk.Button(frame, text=tr.tl('Ignore'), command=self.ignore)
             self.ignore_button.grid(row=2, column=1, sticky=tk.EW)
             self.protocol("WM_DELETE_WINDOW", self._destroy)
 

journal_lock.py

@@ -23,9 +23,6 @@
 from config import config
 from EDMCLogging import get_main_logger
 
-if TYPE_CHECKING:
-    def _(x: str) -> str: return x
-
 # Note that this is also done in EDMarketConnector.py, and thus removing this here may not have a desired effect
 try:
     locale.setlocale(locale.LC_ALL, '')
@@ -61,7 +58,16 @@ def _(x: str) -> str: return x
     GetNumberFormatEx.restype = ctypes.c_int
 
 
-class _Translations:
+class Translations:
+    """
+    The Translation System.
+
+    Contains all the logic needed to support multiple languages in EDMC.
+    DO NOT USE THIS DIRECTLY UNLESS YOU KNOW WHAT YOU'RE DOING.
+    In most cases, you'll want to import translations.
+
+    For most cases: from l10n import translations as tr.
+    """
 
     FALLBACK = 'en'  # strings in this code are in English
     FALLBACK_NAME = 'English'
@@ -79,6 +85,8 @@ def install_dummy(self) -> None:
         Use when translation is not desired or not available
         """
         self.translations = {None: {}}
+        # WARNING: '_' is Deprecated. Will be removed in 6.0 or later.
+        # Migrate to calling Translations.translate directly.
         builtins.__dict__['_'] = lambda x: str(x).replace(r'\"', '"').replace('{CR}', '\n')
 
     def install(self, lang: str | None = None) -> None:  # noqa: CCR001
@@ -88,7 +96,7 @@ def install(self, lang: str | None = None) -> None:  # noqa: CCR001
         :param lang: The language to translate to, defaults to the preferred language
         """
         available = self.available()
-        available.add(_Translations.FALLBACK)
+        available.add(Translations.FALLBACK)
         if not lang:
             # Choose the default language
             for preferred in Locale.preferred_languages():
@@ -122,6 +130,8 @@ def install(self, lang: str | None = None) -> None:  # noqa: CCR001
                 except Exception:
                     logger.exception(f'Exception occurred while parsing {lang}.strings in plugin {plugin}')
 
+        # WARNING: '_' is Deprecated. Will be removed in 6.0 or later.
+        # Migrate to calling Translations.translate directly.
         builtins.__dict__['_'] = self.translate
 
     def contents(self, lang: str, plugin_path: str | None = None) -> dict[str, str]:
@@ -135,12 +145,12 @@ def contents(self, lang: str, plugin_path: str | None = None) -> dict[str, str]:
 
         for line in h:
             if line.strip():
-                match = _Translations.TRANS_RE.match(line)
+                match = Translations.TRANS_RE.match(line)
                 if match:
                     to_set = match.group(2).replace(r'\"', '"').replace('{CR}', '\n')
                     translations[match.group(1).replace(r'\"', '"')] = to_set
 
-                elif not _Translations.COMMENT_RE.match(line):
+                elif not Translations.COMMENT_RE.match(line):
                     logger.debug(f'Bad translation: {line.strip()}')
         h.close()
 
@@ -149,6 +159,10 @@ def contents(self, lang: str, plugin_path: str | None = None) -> dict[str, str]:
 
         return translations
 
+    def tl(self, x: str, context: str | None = None) -> str:
+        """Use the shorthand Dummy loader for the translate function."""
+        return self.translate(x, context)
+
     def translate(self, x: str, context: str | None = None) -> str:
         """
         Translate the given string to the current lang.
@@ -182,11 +196,11 @@ def available_names(self) -> dict[str | None, str]:
         """Available language names by code."""
         names: dict[str | None, str] = {
             # LANG: The system default language choice in Settings > Appearance
-            None: _('Default'),  # Appearance theme and language setting
+            None: self.tl('Default'),  # Appearance theme and language setting
         }
         names.update(sorted(
             [(lang, self.contents(lang).get(LANGUAGE_ID, lang)) for lang in self.available()] +
-            [(_Translations.FALLBACK, _Translations.FALLBACK_NAME)],
+            [(Translations.FALLBACK, Translations.FALLBACK_NAME)],
             key=lambda x: x[1]
         ))  # Sort by name
 
@@ -324,8 +338,21 @@ def preferred_languages(self) -> Iterable[str]:
 
 # singletons
 Locale = _Locale()
-Translations = _Translations()
+translations = Translations()
+
+
+# WARNING: 'Translations' singleton is deprecated. Will be removed in 6.0 or later.
+# Migrate to importing 'translations'.
+# Begin Deprecation Zone
+class _Translations(Translations):
+    def __init__(self):
+        logger.warning(DeprecationWarning('Translations and _Translations() are deprecated. '
+                       'Please use translations and Translations() instead.'))
+        super().__init__()
+
 
+Translations: Translations = _Translations()  # type: ignore # Yes, I know this is awful. But we need it for compat.
+# End Deprecation Zone
 
 # generate template strings file - like xgettext
 # parsing is limited - only single ' or " delimited strings, and only one string per line

l10n.py

@@ -34,10 +34,6 @@
 MAX_NAVROUTE_DISCREPANCY = 5  # Timestamp difference in seconds
 MAX_FCMATERIALS_DISCREPANCY = 5  # Timestamp difference in seconds
 
-if TYPE_CHECKING:
-    def _(x: str) -> str:
-        return x
-
 if sys.platform == 'win32':
     import ctypes
     from ctypes.wintypes import BOOL, HWND, LPARAM, LPWSTR