El texto necesita una arquitectura

1451. Identidad de la lección

Módulo

3.18 — Arquitectura de localización

Lección

El texto necesita una arquitectura

Tipo académico

Sistemas

Tipo de esquema

texto

Orden

1

Tiempo estimado

30–45 minutos, incluida la práctica

1452. Objetivo de aprendizaje

Al finalizar esta lección, podrás definir un contrato de localización para una funcionalidad del juego mediante claves estables, responsabilidades de contenido, cadenas de reserva, parámetros tipados y límites para el formato según la configuración regional.

1453. Por qué importa

El texto localizado es un dato de producto, no una colección de sustituciones repartidas por el código. Una funcionalidad se vuelve difícil de traducir cuando sus claves cambian sin control, no existe una responsabilidad clara sobre las entradas o las reglas de formato se mezclan con el contenido o con el código que llama. Un contrato claro también delimita el uso de la IA: puede ayudar a generar o revisar entradas sin decidir la arquitectura lingüística de la funcionalidad.

1454. Conocimientos previos

Debes poder describir la responsabilidad sobre los datos y los cambios seguros de esquema vistos en el Módulo 3.17, incluida la matriz de migración de 3.17 L2 — Diseñar una migración segura. También debes poder distinguir una regla de la funcionalidad de su presentación e identificar dónde se leen sus datos.

1455. Concepto central

El contenido localizado debe modelarse como datos de producto estructurados y regidos por un contrato explícito.

Un contrato de localización responde cinco preguntas:

1. Clave: ¿Qué identificador semántico estable utiliza la funcionalidad?
2. Responsabilidad de contenido (ownership): ¿Qué funcionalidad o dominio mantiene la entrada?
3. Cadena de reserva (fallback): ¿Qué ocurre cuando no están disponibles la configuración regional o la clave solicitadas?
4. Parámetros: ¿Qué valores con nombre proporciona el código que llama y qué tipos tienen?
5. Política de formato: ¿Qué capa aplica las reglas de números, fechas, horas, unidades, monedas y plurales propias de cada configuración regional?

Una clave debe describir la intención semántica del texto, no su redacción actual. Por ejemplo, delivery.confirmation.ready es más estable que your_order_is_ready, porque puede conservarse durante una revisión de redacción que siga comunicando una confirmación de disponibilidad.

La estabilidad no significa que una clave deba sobrevivir a cualquier cambio de contenido. Si una entrada deja de ser una confirmación y pasa a funcionar como estado neutral, advertencia, pregunta o error, su intención semántica puede haber cambiado. En ese caso hay que revisar la clave. Si el identificador anterior ya no representa el significado nuevo, se crea o se renombra la clave y se documenta la migración del código que llama y de las entradas localizadas.

Asignar una responsabilidad evita definiciones duplicadas o contradictorias. Una funcionalidad o dominio de contenido debe mantener cada entrada. Los demás sistemas la solicitan mediante su clave y sus parámetros, en vez de sustituirla silenciosamente por una frase de otra funcionalidad.

La cadena de reserva debe ser una política deliberada, no el resultado accidental de una búsqueda fallida. Un contrato puede definir es-MX → es → en y, al final, un marcador visible de clave ausente. La cadena concreta puede variar, pero debe ser observable y comprobable.

Los parámetros y la política de formato forman un límite compartido. Por regla general, el código que llama debe proporcionar valores brutos y tipados, como un identificador de destino, una cantidad entera, una fecha, un importe monetario o una medida. La capa de localización o internacionalización debe aplicar las reglas de números, fechas, horas, unidades, monedas y plurales correspondientes a la configuración regional activa. Normalmente no se deben entregar cadenas ya formateadas para una región concreta, porque podrían quedar vinculadas al idioma equivocado o impedir una selección correcta del plural.

La entrada localizada controla el orden de las palabras, la puntuación, la gramática y la ubicación de los parámetros. El código que llama controla el valor de ejecución y su tipo válido. La política de formato identifica qué componente de internacionalización transforma ese valor para la configuración regional activa.

1456. Modelo mental

Usa el modelo CLAVE → RESPONSABLE → RESERVA → PARÁMETROS → POLÍTICA DE FORMATO:

Si una entrada propuesta no puede responder las cinco preguntas, su contrato está incompleto.

1457. Ejemplo concreto

Imagina que una funcionalidad de entregas muestra una confirmación cuando un paquete está listo en un destino.

Un diseño débil podría ser:

show("Your package is ready at " + destinationName + ".")

Aquí la redacción en inglés, la concatenación y el orden de la frase quedan dentro del código que llama. Tampoco se especifican la cadena de reserva ni el formato.

Un contrato más sólido sería:

Key: delivery.confirmation.ready
Owner: delivery
Fallback: es-MX → es → en → [missing: delivery.confirmation.ready]
Parameters:
  destination: string
Formatting policy:
  la entrada localizada controla el orden, la puntuación y la gramática
  el código que llama entrega el valor bruto del destino

Entrada en inglés:

Your package is ready at {destination}.

Entrada en español:

Tu paquete está listo en {destination}.

Un mensaje con una cantidad necesita una política adicional:

Key: delivery.status.packagesReady
Parameters:
  packageCount: integer
Formatting policy:
  la capa de localización formatea el número y selecciona el plural adecuado

El código entrega un entero, no un número con formato inglés ni una frase ya construida. La implementación completa del formateador queda fuera de esta lección, pero el contrato debe indicar qué capa asume esa responsabilidad.

1458. Cambios de redacción y cambios semánticos

Un cambio de redacción conserva la función comunicativa del mensaje. Por ejemplo, cambiar “Your package is ready at {destination}” por “Your package is now ready at {destination}” sigue comunicando una confirmación de disponibilidad. Por tanto, delivery.confirmation.ready puede seguir siendo una clave adecuada.

Un cambio semántico modifica la función del mensaje. Sustituir esa confirmación por “Package status: {destination}” puede convertirla en una etiqueta de estado neutral. Mantener delivery.confirmation.ready sería engañoso. El contrato debe exigir una revisión semántica, una clave nueva o renombrada cuando sea necesario y una migración explícita del código que llama y de las entradas localizadas.

1459. Errores comunes

• Nombrar entradas según su posición en pantalla o su redacción actual, como button_text_2.
• Concatenar valores de ejecución dentro de frases traducidas.
• Permitir que cada punto de llamada invente su propia cadena de reserva.
• Entregar fechas, monedas, cantidades o unidades ya formateadas sin una razón documentada.
• Suponer que una clave estable nunca debe cambiar aunque cambie la intención del mensaje.
• Tratar el inglés como reserva neutral sin documentar las variantes regionales, el idioma base y el comportamiento ante claves ausentes.

1460. Práctica guiada

Crea un contrato de localización para una funcionalidad pequeña, como una confirmación de entrega, una advertencia de inventario, una etiqueta de destino del mapa o un control de ajustes. Define la arquitectura antes de escribir una tabla completa de traducciones.

Registra estas decisiones:

1. Escribe tres claves semánticas y estables. Evita nombres basados en la posición en pantalla o en la redacción inglesa actual.
2. Asigna una funcionalidad o dominio responsable a cada clave.
3. Define una cadena de reserva para una configuración regional, un idioma base y el comportamiento final ante una clave ausente.
4. Para un mensaje dinámico, enumera cada parámetro con nombre y su tipo esperado.
5. Añade una política de formato. Indica que el código proporciona valores brutos y tipados, e identifica qué capa aplica las reglas regionales de números, fechas, horas, unidades, monedas o plurales que necesite el mensaje.
6. Indica qué controla la entrada localizada y qué permanece como dato de ejecución.

Prueba el contrato con dos cambios:

• Cambio de redacción: cambia “Your package is ready at {destination}” por “Your package is now ready at {destination}”. Explica por qué puede conservarse la clave semántica.
• Posible cambio semántico: sustituye la confirmación por un mensaje de estado neutral. Decide si la clave original todavía representa el mensaje. Si no es así, propón una clave nueva o renombrada y una migración para el código que llama y las entradas localizadas.

1461. Validación y evidencia

1462. Ideas clave

• El texto localizado es un dato de producto estructurado con responsabilidades y comportamiento explícitos.
• Las claves estables representan la intención semántica, no la redacción actual ni la posición en la interfaz.
• Un cambio de redacción puede conservar la clave; un cambio de significado exige una revisión semántica y puede requerir una clave nueva o renombrada junto con su migración.
• La cadena de reserva debe estar ordenada y ser observable y comprobable.
• El código debe proporcionar valores brutos y tipados; la capa de localización o internacionalización aplica el formato y las reglas de plural propias de cada configuración regional.
• Las entradas localizadas controlan la estructura de la frase, la puntuación, la gramática y la ubicación de los parámetros.

1463. Comprobación de conocimientos

1464. Siguiente lección

Continúa con 3.18 L2 — Validar los recorridos en inglés y español y utiliza como casos de validación tus claves, cadena de reserva, tipos de parámetros, política de formato y comportamiento ante claves ausentes.

1465. Comprobación