From 650f7cd6d7268a03dfd8625128507c4e3b7d2c7d Mon Sep 17 00:00:00 2001 From: yyc12345 Date: Thu, 17 Sep 2026 20:49:45 +0800 Subject: [PATCH] doc: add standard version mark in code comment --- src/metaglot/langid.py | 24 ++++++++++++++++++++++ src/metaglot/langmap/appstream_lang_map.py | 7 ++++++- src/metaglot/langmap/desktop_lang_map.py | 6 ++++++ src/metaglot/langmap/win_lcid_map.py | 23 +++++++++++++++------ 4 files changed, 53 insertions(+), 7 deletions(-) diff --git a/src/metaglot/langid.py b/src/metaglot/langid.py index 557c155..7d82d7f 100644 --- a/src/metaglot/langid.py +++ b/src/metaglot/langid.py @@ -3,6 +3,11 @@ from typing import ClassVar, Optional import langcodes import pycountry +# YYC MARK: +# This class is declared for GNU Gettext PO file. +# The standard of this can be seen at: +# https://www.gnu.org/software/gettext/manual/html_node/Header-Entry.html + class PoLang: """ @@ -128,6 +133,13 @@ class PoLang: # endregion +# YYC MARK: +# This class is declared for FreeDesktop ``.desktop`` file. +# The standard of this can be seen at: +# https://specifications.freedesktop.org/desktop-entry/1.5/localized-keys.html +# The adopted version of specification is **1.5** . + + class DesktopLang: """ Represents a freedesktop.org desktop entry locale, i.e. the ``LOCALE`` @@ -255,6 +267,12 @@ class DesktopLang: # endregion +# YYC MARK: +# AppStream XML file use standard ``xml:lang`` attribute to mark languages and locales. +# So according to XML standard, the value of it must follow BCP 47. +# This class is created for it so it should validate it. + + class AppStreamLang: """ Represents a BCP 47 language tag, as required by the ``xml:lang`` @@ -350,6 +368,12 @@ class AppStreamLang: # endregion +# YYC MARK: +# The class is defined for Microsoft LCID. +# See: https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-lcid/70feba9f-294e-491e-b6eb-56532684c37f +# The adopted version of specification [MS-LCID] is **revision 2024-04-23** . + + class WinLcid: """ Represents a Windows language identifier (LANGID), the 2-byte language diff --git a/src/metaglot/langmap/appstream_lang_map.py b/src/metaglot/langmap/appstream_lang_map.py index cbeeab0..168f5e0 100644 --- a/src/metaglot/langmap/appstream_lang_map.py +++ b/src/metaglot/langmap/appstream_lang_map.py @@ -1,6 +1,11 @@ from ..langid import AppStreamLang, PoLang -# YYC MARK: Gettext's variant slot may hold either a script designator or a +# YYC MARK: +# AppStream XML file use standard ``xml:lang`` attribute to mark languages and locales. +# So according to XML standard, the value of it must follow BCP 47. + +# YYC MARK: +# Gettext's variant slot may hold either a script designator or a # genuine variant, and BCP 47 places the two at different positions with # different vocabularies ('latin' != 'Latn'), so the conversion cannot be # done mechanically. Candidate matching is done here as a workaround, with diff --git a/src/metaglot/langmap/desktop_lang_map.py b/src/metaglot/langmap/desktop_lang_map.py index 38ea6e2..75f2182 100644 --- a/src/metaglot/langmap/desktop_lang_map.py +++ b/src/metaglot/langmap/desktop_lang_map.py @@ -1,6 +1,12 @@ from ..langid import DesktopLang, PoLang +# YYC MARK: +# The standard of this convertion procedure can be seen at: +# https://specifications.freedesktop.org/desktop-entry/1.5/localized-keys.html +# The adopted version of specification is **1.5** . + + def convert(lang: PoLang) -> DesktopLang: """ Convert a PO file language to a desktop entry locale. diff --git a/src/metaglot/langmap/win_lcid_map.py b/src/metaglot/langmap/win_lcid_map.py index 13b85da..6a39afe 100644 --- a/src/metaglot/langmap/win_lcid_map.py +++ b/src/metaglot/langmap/win_lcid_map.py @@ -1,24 +1,35 @@ from ..langid import PoLang, WinLcid -# YYC MARK: The table below is transcribed from the 'Language ID' table in + +# YYC MARK: +# The standard of this convertion procedure can be seen at: +# https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-lcid/70feba9f-294e-491e-b6eb-56532684c37f +# The adopted version of specification [MS-LCID] is **revision 2024-04-23** . +# +# The table below is transcribed from the 'Language ID' table in # [MS-LCID] section 2.2 (revision 2024-04-23). Underscore separators in the # original language tags have been normalized to hyphens # (e.g. 'es-ES_tradnl' -> 'es-ES-tradnl'). -# YYC MARK: Rows whose tags are marked 'reserved' in the document are kept +# +# Rows whose tags are marked 'reserved' in the document are kept # for transcription fidelity but commented out with a leading '#', so they # carry no runtime effect and lookups on them fail. -# YYC MARK: Rows without a usable language tag are omitted entirely: values +# +# Rows without a usable language tag are omitted entirely: values # that are neither defined nor reserved, the invariant-locale value 0x007F, # the user-default and unspecified placeholders 0x0C00/0x1000 (harmful # process-local values that must never be persisted into RC resources), and # the transient LCIDs 0x2000-0x4C00. -# YYC MARK: Rows carrying multiple tags for one value (e.g. +# +# Rows carrying multiple tags for one value (e.g. # 'ff-NG, ff-Latn-NG') are expanded into consecutive entries sharing the # same WinLcid. -# YYC MARK: The alternate-sort table of section 2.2 (full 4-byte LCIDs with +# +# The alternate-sort table of section 2.2 (full 4-byte LCIDs with # sort identifiers, e.g. 'de-DE_phoneb' 0x00010407) is not transcribed: # WinLcid only models the 2-byte language identifier used by RC resources. -# YYC MARK: Known contradiction inside the document: the appendix assigns +# +# Known contradiction inside the document: the appendix assigns # 'quc' -> 0x0086 and 'quc-Latn-GT' -> 0x0486, while the section 2.2 registry # has 'qut' -> 0x0086 and marks 'quc' (0x0093), 'qut-GT' (0x0486) and # 'quc-CO' (0x0493) as reserved. The section 2.2 registry wins here.