languageHandler module

Language and localization support. This module assists in NVDA going global through language services such as converting Windows locale ID’s to friendly names and presenting available languages.

languageHandler.LCID_NONE = 0

Returned from L{localeNameToWindowsLCID} when the locale name cannot be mapped to a locale identifier. This might be because Windows doesn’t know about the locale (e.g. “an”), because it is not a standardized locale name anywhere (e.g. “zz”) or because it is not a legal locale name (e.g. “zzzz”).

languageHandler.installedTranslation: ReferenceType | None = <weakref at 0x050B0C58; to 'NullTranslations'>

Saved copy of the installed translation for ease of wrapping.

languageHandler.LCIDS_TO_TRANSLATED_LOCALES = {1170: 'ckb'}

Map Windows locale identifiers to language codes. These are Windows LCIDs that are used in NVDA but are not found in locale.windows_locale. These have been added when new locales have been introduced to the translation system and we cannot use the results from the Windows function LCIDToLocaleName.

class languageHandler.LOCALE(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

SLANGUAGE = 2
SLIST = 12
IMEASURE = 13
SLANGDISPLAYNAME = 111
SENGLISHLANGUAGENAME = 4097
SENGLISHCOUNTRYNAME = 4098
IDEFAULTANSICODEPAGE = 4100
languageHandler.isNormalizedWin32Locale(localeName: str) bool

Checks if the given locale is in a form which can be used by Win32 locale functions such as GetLocaleInfoEx. See normalizeLocaleForWin32 for more comments.

languageHandler.normalizeLocaleForWin32(localeName: str) str

Converts given locale to a form which can be used by Win32 locale functions such as GetLocaleInfoEx unless locale is normalized already. Uses hyphen as a language/country separator taking care not to replace underscores used as a separator between country name and alternate order specifiers. For example locales using alternate sorts see: https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-lcid/e6a54e86-9660-44fa-a005-d00da97722f2 While NVDA does not support locales requiring multiple sorting orders users may still have their Windows set to such locale and if all underscores were replaced unconditionally we would be unable to generate Python locale from their default UI language.

languageHandler.localeNameToWindowsLCID(localeName: str) int

Retrieves the Windows locale identifier (LCID) for the given locale name @param localeName: a string of 2letterLanguage_2letterCountry or just language (2letterLanguage or 3letterLanguage) @returns: a Windows LCID or L{LCID_NONE} if it could not be retrieved.

languageHandler.windowsLCIDToLocaleName(lcid: int) str | None

Gets a normalized locale from a Windows LCID.

NVDA should avoid relying on LCIDs in future, as they have been deprecated by MS: https://docs.microsoft.com/en-us/globalization/locale/locale-names

languageHandler.getLanguageDescription(language: str) str | None

Finds out the description (localized full name) of a given local name

languageHandler.englishLanguageNameFromNVDALocale(localeName: str) str | None

Returns either English name of the given language using GetLocaleInfoEx or None if the given locale is not known to Windows.

languageHandler.englishCountryNameFromNVDALocale(localeName: str) str | None

Returns either English name of the given country using GetLocaleInfoEx or None if the given locale is not known to Windows.

languageHandler.ansiCodePageFromNVDALocale(localeName: str) str | None

Returns either ANSI code page for a given locale using GetLocaleInfoEx or None if the given locale is not known to Windows.

languageHandler.listNVDALocales() List[str]
languageHandler.getAvailableLanguages(presentational: bool = False) List[Tuple[str, str]]

generates a list of locale names, plus their full localized language and country names. @param presentational: whether this is meant to be shown alphabetically by language description

languageHandler.getLanguageCliArgs() Tuple[str, ...]

Returns all command line arguments which were used to set current NVDA language or an empty tuple if language has not been specified from the CLI.

languageHandler.isLanguageForced() bool

Returns True if language is provided from the command line - False otherwise.

languageHandler.getWindowsLanguage()

Fetches the locale name of the user’s configured language in Windows.

languageHandler._createGettextTranslation(localeName: str) None | GNUTranslations | NullTranslations
languageHandler.setLanguage(lang: str) None
Sets the following using lang such as “en”, “ru_RU”, or “es-ES”. Use “Windows” to use the system locale
  • the windows locale for the thread (fallback to system locale)

  • the translation service (fallback to English)

  • Current NVDA language (match the translation service)

  • the python locale for the thread (match the translation service, fallback to system default)

languageHandler.localeStringFromLocaleCode(localeCode: str) str

Given an NVDA locale such as ‘en’ or or a Windows locale such as ‘pl_PL’ creates a locale representation in a standard form for Win32 which can be safely passed to Python’s setlocale. The required format is: ‘englishLanguageName_englishCountryName.localeANSICodePage’ Raises exception if the given locale is not known to Windows.

languageHandler._setPythonLocale(localeString: str) bool

Sets Python locale to a specified one. Returns True if succesfull False if locale cannot be set or retrieved.

languageHandler.setLocale(localeName: str) None

Set python’s locale using a localeName such as “en”, “ru_RU”, or “es-ES”. Will fallback on current NVDA language if it cannot be set and finally fallback to the system locale. Passing NVDA locales straight to python locale.setlocale does now work since it tries to normalize the parameter using locale.normalize which results in locales unknown to Windows (Python issue 37945). For example executing: locale.setlocale(locale.LC_ALL, "pl") results in locale being set to ('pl_PL', 'ISO8859-2') which is meaningless to Windows,

languageHandler.getLanguage() str
languageHandler.normalizeLanguage(lang: str) str | None

Normalizes a language-dialect string in to a standard form we can deal with. Converts any dash to underline, and makes sure that language is lowercase and dialect is upercase.

languageHandler.useImperialMeasurements() bool

Whether or not measurements should be reported as imperial, rather than metric.

languageHandler.stripLocaleFromLangCode(langWithOptionalLocale: str) str

Get the lang code eg “en” for “en-au” or “chr” for “chr-US-Qaaa-x-west”. @param langWithOptionalLocale: may already be language only, or include locale specifier (e.g. “en” or “en-au”). @return The language only part, before the first dash.