Internacionalización (i18n)

Los productos y la documentación del ecosistema se ofrecen en varios idiomas. Esta página explica la política lingüística y su implementación técnica.

Política lingüística

Nivel	Idiomas
Obligatorio	Монгол (mn) · English (en)
Para los productos principales	+ 中文 (zh) · Русский (ru)
Para la documentación de ecosistema	Mongol + los seis idiomas oficiales de la ONU

El mongol es la lengua de origen: el texto original se escribe en mongol y desde ahí se traduce.

Los seis idiomas oficiales de las Naciones Unidas son: العربية (ar) · 中文 (zh) · English (en) · Français (fr) · Русский (ru) · Español (es). Este sitio (documentación a nivel de ecosistema) se publica en mongol más esos seis — siete en total.

¿Por qué precisamente estos idiomas?

Quienes leen la documentación de ecosistema no son solo desarrolladores internos: también hay socios internacionales, organismos donantes, entidades de normalización e integradores extranjeros. Los seis idiomas de la ONU ofrecen el mayor alcance global y son una elección neutral, que no privilegia a ningún país.

La documentación técnica profunda de cada plataforma (esquemas de endpoints, referencia de SDK) queda fuera de esta política: se mantiene en MN + EN dentro de su propio repositorio.

i18n en los productos

Las aplicaciones determinan el idioma del usuario en este orden:

1. La preferencia del usuario (guardada en su perfil),
2. El Accept-Language del navegador,
3. El idioma por defecto (mn).

El asistente de IA responde en el idioma del usuario, el mismo en que llegó la pregunta.

Las dos capas del diccionario

El diccionario vive en dos sitios, y entender la frontera entre ambos importa:

Diccionario	Dónde	Tamaño
Compartido — inicio de sesión, menú, administración, eID	@gerege/ui-core	846 claves × 7 idiomas
De plataforma — la terminología de ese sector	lib/<platform>I18n.ts	Distinto en cada plataforma, normalmente 2–4 idiomas

La regla: el diccionario compartido solo conoce la superficie compartida. El vocabulario de IBAN y extractos del monedero, el catálogo de API del portal de desarrolladores, la terminología de procesos de negocio de Ring: todo eso reside en el diccionario propio de la aplicación.

El motivo es el coste: meter los 1,104 términos de Ring en el diccionario compartido hace que kiosk, POS y el monedero carguen con ellos, y con cada idioma añadido ese coste se multiplica por siete.

El diccionario de plataforma recurre al inglés en los idiomas sin traducir, de modo que la interfaz puede estar en siete idiomas mientras el texto de marketing y la terminología sectorial existen en menos.

Idioma de interfaz ≠ idioma de contenido

Ampliar el diccionario de cuatro idiomas a siete rompió todos los puntos donde figuraba Record<Lang, …>: el texto de marketing de la landing, las descripciones del catálogo de API. Esos textos los escribe una persona y no crecen igual que la interfaz. En esos puntos, el conjunto de idiomas se declara de forma explícita, por ejemplo como LANDING_LANGS.

i18n en la documentación

El sitio de documentación de cada repositorio usa MkDocs Material + mkdocs-static-i18n.

La estructura por sufijo

La traducción se hace añadiendo el código de idioma al nombre del fichero:

docs/
├── index.md        ← Монгол (por defecto)
├── index.ar.md     ← العربية
├── index.zh.md     ← 中文
├── index.en.md     ← English
├── index.fr.md     ← Français
├── index.ru.md     ← Русский
└── index.es.md     ← Español

Configuración:

plugins:
  - i18n:
      docs_structure: suffix
      fallback_to_default: true
      reconfigure_material: true
      reconfigure_search: true
      languages:
        - locale: mn
          default: true
          name: Монгол
          build: true
        - locale: en
          name: English
          build: true
        - locale: ar
          name: العربية
          build: true
        # … zh · fr · ru · es igual

El idioma por defecto se construye en la raíz del sitio (/) y los demás bajo una subruta (/en/, /ar/, /zh/, /fr/, /ru/, /es/).

Fallback

fallback_to_default: true: una página sin traducir muestra su contenido en el idioma por defecto. Así, aunque falten traducciones, el sitio sigue completo y no aparece ningún 404.

Es la decisión práctica: la documentación crece constantemente y la traducción va por detrás. Esperar a tener todas las páginas traducidas a la vez equivale a no publicar la documentación.

Traducción de la navegación

Las etiquetas del menú no están en el contenido de las páginas, sino en mkdocs.yml, así que se traducen por separado para cada locale:

        - locale: en
          nav_translations:
            Архитектур: Architecture
            Платформууд: Platforms
        - locale: ar
          nav_translations:
            Архитектур: البنية المعمارية
            Платформууд: المنصّات

Si añade una página y olvida incluir su entrada de nav_translations en los seis locales, esa etiqueta de menú se quedará en mongol: la construcción no falla, así que solo se detecta a simple vista.

Escritura de derecha a izquierda (RTL)

العربية se lee de derecha a izquierda. Material reconoce el locale ar, pone <html dir="rtl"> y voltea por sí mismo el menú, los títulos y el flujo de las tablas: no hace falta indicar direction aparte.

En cambio, los bloques de código y los diagramas ASCII siguen de izquierda a derecha incluso en RTL. Y así debe ser: la notación técnica (URL, comandos, YAML) pierde su sentido si se invierte la dirección.

Anclas para títulos en cirílico

El slugify estándar descarta las letras cirílicas

El slugify por defecto de la extensión toc de Python-Markdown elimina los caracteres no ASCII. Por eso el título ## Танилт recibe un id vacío y el enlace interno de la página (#танилт) deja de funcionar.

La solución es un slugify que conserve el unicode:

markdown_extensions:
  - toc:
      permalink: true
      slugify: !!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}}

Este sitio está configurado igual.

El orden de traducción

Al añadir documentación nueva:

1. Escriba el texto de origen en mongol: la fuente siempre es el mongol.
2. Estabilice la versión mongola con una construcción estricta (se comprueban enlaces y anclas).
3. Después traduzca a los seis idiomas de una vez. Traducir una página a medias descuadra unos idiomas respecto de otros.

Termine una página en todos los idiomas

Conviene trabajar página a página y no idioma a idioma: convertir un mismo documento a seis idiomas a la vez mantiene idénticas la terminología, la estructura y las filas de las tablas. Al revés — «primero todas las páginas en inglés» — los idiomas traducidos después irán persiguiendo un texto de origen que ya ha cambiado.

Qué se traduce y qué no

Se traduce	Se deja tal cual
Texto corrido, títulos, valores de las tablas	Nombres de dominio (sso.gerege.mn)
Explicaciones, advertencias, consejos	Nombres de repositorio (template-gerege-mn)
Etiquetas explicativas dentro de los diagramas	Código, YAML, comandos, rutas de endpoints
Cabeceras de tabla	Nombres de producto (eID Mongolia, G-Sign)
Texto de las etiquetas de estado	Nombres de estándares (OIDC, PKCE, RFC 3161)

Los nombres de fichero y la estructura de carpetas no se traducen nunca: es platforms/sso.ru.md, no платформы/sso.md. Así la ruta de la URL no cambia al pasar de un idioma a otro y los enlaces profundos siguen funcionando.

El estado de este sitio

Todas las páginas de la documentación de ecosistema están listas en siete idiomas:

Locale	Idioma	Ruta	Estado
mn	Монгол (por defecto)	/	✅ completo
ar	العربية	/ar/	✅ completo
zh	中文	/zh/	✅ completo
en	English	/en/	✅ completo
fr	Français	/fr/	✅ completo
ru	Русский	/ru/	✅ completo
es	Español	/es/	✅ completo

fallback_to_default sigue activado: cuando se añada una página y su traducción vaya con retraso, esa página mostrará el original mongol y el sitio seguirá completo.

Si detecta un error o una expresión poco afortunada, envíe un PR al repositorio — véase Esta plataforma documental.