Configuración regional

El título/descripción de cada regla, y el resumen/pista de cada ocurrencia, se localizan mediante una búsqueda en un diccionario basado en claves: no están codificados de forma fija por idioma.

Cobertura actual de configuración regional

Los archivos de configuración regional son JSON simples: un mapa plano de clave a cadena traducida, en el mismo orden de claves que en.json. No contienen nada más, así que contribuir con un idioma significa editar texto y nunca tocar código.

Cada configuración regional contiene todas las claves que tiene en.json. Mantenerlo así es tarea de npm run i18n:sync: ejecútalo después de cualquier cambio en en.json y reescribe cada archivo de configuración regional no inglés para que coincida: añadiendo claves nuevas, eliminando claves que en.json ya no tiene, y dejando intactas las traducciones existentes. Una clave que añade se inicializa con el texto en inglés, lo cual cuenta como no traducido hasta que alguien lo reemplace.

Seleccionar una configuración regional

runDomRulesInPage(url, null, { locale: 'fr' }, null);

El valor predeterminado es 'en' si se omite. Se acepta cualquier cadena; una configuración regional no reconocida nunca es un error.

Cómo se elige una configuración regional

Ocurren dos cosas, en este orden. Confundirlas es la fuente habitual de confusión, así que se describen por separado.

Paso 1: elegir un diccionario (una vez por análisis)

1. Usa el diccionario que coincide con tu código. de encuentra de.json. Las mayúsculas/minúsculas no importan: pt-br, pt-BR y PT-BR encuentran todos pt-BR.json.
2. Si no, elimina todo lo que sigue al primer - y prueba con eso. de-DE encuentra de.json; de-AT también.
3. Si no, usa inglés.

Así que solo necesitas un de-DE.json si el alemán de Austria y de Alemania realmente debe leerse de forma distinta. Publica de.json y toda variante de alemán queda cubierta.

Paso 2: resolver cada cadena (por cadena)

Dentro del diccionario elegido, cada cadena se busca de forma individual:

1. Toma el valor de la clave del diccionario elegido.
2. Si esa clave falta, toma la inglesa.
3. Si el inglés tampoco la tiene (algo que no debería ocurrir con una clave incorporada, pero puede pasar con una escrita a mano), usa el texto literal que la propia regla lleva.

El resultado nunca es un vacío, un undefined, ni un error lanzado. Una traducción a medias se muestra en tu idioma donde existe y en inglés en todo lo demás.

Saber qué configuración regional obtuviste realmente

El respaldo elegante tiene un inconveniente: pide un idioma que la compilación no incluye y obtienes inglés fluido de vuelta, sin nada en las cadenas que lo indique. Por eso cada resultado informa la resolución una vez, al principio:

"engine": {
  "tag": "a11ycore",
  "schemaVersion": "1.0.0",
  "locale": { "requested": "ja", "resolved": "en", "reason": "unknown-locale" }
}

requested es lo que pediste (después de recortar espacios; en si no pasaste nada o pasaste algo que no es una cadena), resolved es el diccionario que se usó, y reason es uno de los siguientes:

Trata la lista como abierta: una versión posterior puede añadir un valor, así que compara solo con los que te interesan y deja que el resto caiga en un valor por defecto.

Si necesitas un idioma concreto, requested !== resolved es la condición que hay que comprobar en CI. Ten en cuenta que también es cierta para el caso inofensivo de primary-subtag, así que condiciónalo a reason === 'unknown-locale' || reason === 'dictionary-not-loaded' si una coincidencia de idioma base te resulta suficiente. Consulta el esquema de salida para conocer el lugar de este campo en el resultado, y API_STABILITY.md para saber qué se garantiza sobre él.

Dónde viven los diccionarios

Qué idiomas están disponibles depende de cómo cargues el motor.

El paquete está dividido porque viaja por la red a cada página que lo usa, y ninguna página necesita los cuatro idiomas. Mantener el inglés incorporado y el resto como opcional redujo unos 280 KB de la descarga y evita que siga creciendo a medida que se añaden idiomas. Nada más cambia: el paquete de Node y las integraciones no se ven afectados.

<script src="surea11y.browser.js"></script>
<script src="surea11y.i18n.de.js"></script>

Pide un idioma cuyo archivo no cargaste y obtienes inglés, con engine.locale.reason establecido en dictionary-not-loaded, distinto de unknown-locale, que significa que el proyecto no tiene esa traducción en absoluto.

Proporcionar tu propio diccionario

engineOptions.messages acepta { [locale]: { key: value } } y tiene prioridad sobre cualquier cosa incorporada o cargada desde un archivo lateral. Útil para sobrescribir un puñado de cadenas o para un idioma que mantienes de forma privada:

runDomRulesInPage(url, null, {
  locale: 'de',
  messages: { de: { img_altPresent_title: 'Eigener Text' } }
}, null);

Las claves que no proporciones recurren al valor por defecto normalmente, así que una sobrescritura parcial es válida.

Dónde se usan las claves

Dos espacios de nombres de claves independientes, ambos resueltos de la misma manera:

• A nivel de regla: meta.i18n.titleKey / meta.i18n.descriptionKey, resuelven el title/description de una regla en cada entrada de checksResults[].
• A nivel de ocurrencia: i18n.summaryKey / i18n.hintKey, con i18n.params para la interpolación de {{placeholder}}, resuelven el summary/hint de una ocurrencia. Consulta el esquema de salida.

Ambas se incluyen en el resultado junto con el texto ya resuelto, así que puedes volver a renderizar en una configuración regional distinta a partir de un resultado guardado sin volver a analizar.