5. Internacionalización
Una aplicación internacionalizada muestra su texto en el idioma del usuario. El caso de estudio está en francés e inglés. El principio es simple: las vistas ya no contienen texto, sino claves ([MENU.HOME]), y un diccionario para cada idioma asocia un texto a cada clave. El idioma seleccionado se almacena en una cookie.
[Spring] tiene su propio sistema de traducción: la interfaz [MessageSource], cuya implementación estándar lee archivos como [messages_fr.properties], [messages_en.properties]... Conservaremos la interfaz, ya que [Spring] y [Thymeleaf] la usan para traducir, pero la implementaremos nosotros mismos, con una pequeña clase que lee diccionarios JSON: son los mismos archivos que los de las versiones [ASP.NET Core MVC] y [NestJS] del caso de estudio, y su formato se puede leer y escribir sin herramientas especiales. En cambio, dejaremos que [Spring MVC] se encargue de la selección del idioma en cada solicitud: este es el papel de su resolvedor de idioma ([LocaleResolver]), que vimos en el Ejemplo 16.
5.1. Ejemplo 22: Una aplicación bilingüe
Los archivos [pom.xml] (el starter [Thymeleaf]), [application.properties] (puerto 5000), [Example22Application.java] (la clase de inicio) y [styles.css] son los mismos que los de los ejemplos anteriores.
5.1.1. Los diccionarios
El archivo [src/main/resources/i18n/fr.json]:
El archivo [src/main/resources/i18n/en.json]:
- Un diccionario es un archivo JSON, organizado por página o por tema: la clave [HOME.HELLO] hace referencia al texto [HELLO] de la sección [HOME];
- Línea 8: un texto puede contener parámetros, encerrados entre llaves, que se reemplazan durante la traducción. El orden de las palabras varía de un idioma a otro: por eso un texto no se crea simplemente concatenando segmentos traducidos.
Los diccionarios se colocan en [src/main/resources]: [Maven] copia esta carpeta en [target/classes], junto con las clases compiladas. Por lo tanto, forman parte de la classpath: el conjunto de carpetas y archivos comprimidos donde [Java] busca las clases y los recursos de la aplicación: ahí es donde el programa los leerá, sin importar desde qué carpeta se inicie.
5.1.2. El servicio de traducción
El archivo [translation/Translator.java], en dos partes. La primera parte lee los diccionarios y traduce:
Analicemos este código:
- líneas 24–25: el servicio es un bean (anotado con [@Component]) y, por lo tanto, un singleton: los archivos se leen una sola vez, al iniciar. Implementa la interfaz [MessageSource] de [Spring] y se llama [messageSource], como lo especifica la anotación. Este nombre no se elige al azar: es con este nombre que [Spring] busca el servicio de traducción de la aplicación. [Spring Boot], que crea uno de forma predeterminada (leería los archivos [messages*.properties]), se abstiene de hacerlo en cuanto existe un bean con ese nombre;
- líneas 27–28: los idiomas admitidos y el idioma predeterminado. [List.of] crea una lista de solo lectura;
- línea 31: la expresión regular [\{(\w+)\}] (una llave de apertura, uno o más caracteres de palabra, capturados, una llave de cierre), que identifica los parámetros en un texto. En una cadena [Java], la barra invertida se escribe como [\\]. [Pattern.compile] la analiza una sola vez;
- línea 34: para cada idioma, un diccionario [Java] ([Map]) que asocia cada clave completa ([HOME.HELLO]) con su texto;
- líneas 36–46: el constructor lee los archivos JSON. [ClassPathResource] hace referencia a un archivo de la classpath (vea más arriba). La instrucción [try (...)] (conocida como instrucción “try-with-resources”) cierra automáticamente el flujo abierto entre sus paréntesis al final del bloque, incluso si se produce un error. El objeto [ObjectMapper] de la biblioteca [Jackson] (la que [Spring] usa para JSON) analiza el texto y lo convierte en un árbol de nodos [JsonNode];
- líneas 49–52: el idioma admitido más cercano a un idioma dado. Un objeto [Locale] de tipo [Java] denota un idioma, posiblemente especificado por un país ([fr], [en_US]...); [getLanguage()] proporciona su código de dos letras. Un idioma no admitido ([de]) devuelve el idioma predeterminado;
- líneas 56–72: la traducción. La clave se busca en el diccionario del idioma solicitado; si no se encuentra, se muestra la propia clave ([getOrDefault]): una omisión es inmediatamente visible en la pantalla;
- líneas 65–68: los parámetros se almacenan en un arreglo [Object[]], como pares (nombre, valor): [["name", "Marie"]]. El bucle los organiza en un diccionario [name -> value]. Veremos por qué se eligió este formato algo inusual;
- líneas 70–71: [replaceAll] reemplaza cada parámetro [{name}] que se encuentra en el texto por el resultado de la lambda: el valor del parámetro con el mismo nombre ([r.group(1)] es la parte capturada entre paréntesis), o el parámetro mismo, sin cambios, si no tiene valor ([r.group()] es el texto completo encontrado). [Matcher.quoteReplacement] protege los caracteres [$] y [\] que un valor podría contener, y que de otro modo tienen un significado especial para [replaceAll];
- Líneas 75–84: el método “aplana” el JSON: el objeto ["HOME": { "HELLO": "..." }] produce la clave [HOME.HELLO]. Se llama a sí mismo (método recursivo) para recorrer objetos anidados. [properties()] devuelve los pares (nombre, valor) de un objeto JSON; [asString()] devuelve el valor de un texto.
La segunda parte implementa la interfaz [MessageSource]:
- líneas 3–11: los dos métodos que traducen un código (una clave) y sus argumentos a un idioma dado; llaman a [translate]. La anotación [@Override] indica al compilador que verifique que, efectivamente, se sobrescribe un método de la interfaz;
- líneas 15–26: el tercer método recibe un objeto [MessageSourceResolvable], que describe un mensaje mediante varios códigos posibles, desde el más específico hasta el más general. Así es como [Spring] describe los errores de validación (vea el Ejemplo 19): una restricción [@NotBlank] en el campo [name] de un objeto [person] produce los códigos [NotBlank.person.name], [NotBlank.name], [NotBlank]... Tiene prioridad el primer código presente en el diccionario; si no hay ninguno, se devuelve el mensaje predeterminado o el primer código. El caso de estudio usa esto para traducir sus mensajes de error.
En [Spring], el formato habitual de los parámetros de un mensaje es posicional: [Hello {0}!], donde el primer argumento reemplaza a [{0}]. Preferimos los parámetros con nombre, que son más legibles en un diccionario ([Hello {name}!]) e idénticos a los de otras versiones del caso de estudio. Sin embargo, la interfaz [MessageSource] solo pasa un arreglo de argumentos; de ahí la convención de pares (nombre, valor).
5.1.3. Traducción en las vistas
En una vista [Thymeleaf], la expresión [#{KEY}], introducida simplemente por el arreglo del Ejemplo 14, es la traducción de la clave [KEY] al idioma de la solicitud: [Thymeleaf] llama al bean [messageSource], es decir, a nuestro [Translator]. Los argumentos se pasan entre paréntesis: [#{HOME.HELLO('name', ${name})}] llama a [getMessage("HOME.HELLO", ["name", "Marie"], language)]. No es necesario escribir ninguna clase del lado de la vista: esta es la ventaja de haber implementado la interfaz de [Spring].
Quedan las fechas y los montos, que no se traducen pero sí se formatean según el idioma. El archivo [translation/Formats.java]:
Esta es, más o menos, la clase del Ejemplo 16:
- línea 14: un bean llamado [formats], al que las vistas hacen referencia como [${@formats.longDate(...)}];
- líneas 19 y 24: [LocaleContextHolder.getLocale()] especifica el idioma de la solicitud actual. Veremos quién lo establece;
- línea 19: una fecha en formato largo ([FormatStyle.FULL]), en ese idioma;
- líneas 24–26: un monto, en el formato monetario de ese idioma, en euros sin importar el idioma.
5.1.4. Selección del idioma
El archivo [config/WebConfig.java]:
Analicemos este código:
- Líneas 19–25: los archivos de [Bootstrap], como en los ejemplos anteriores;
- Líneas 29–37: el bean [localeResolver] (que es el nombre con el que [Spring MVC] lo busca) establece el idioma de cada solicitud. Al comienzo de cada solicitud, [Spring MVC] le pide el idioma y lo almacena en [LocaleContextHolder] durante toda la solicitud: los métodos de [Formats], las expresiones [#{...}] de [Thymeleaf] y la variable [#locale] en las vistas lo recuperan de ahí;
- línea 31: un [CookieLocaleResolver], proporcionado por [Spring], lee el idioma de una cookie, aquí llamada [language]. La cookie contiene el código del idioma ([en]);
- línea 32: sin cookie, el idioma es el inglés. Observe que el idioma del navegador (encabezado [Accept-Language]) se ignora entonces: el usuario elige el idioma con los botones FR / EN;
- Líneas 33–35: las características de la cookie que [CookieLocaleResolver] escribirá cuando se cambie el idioma: una duración de un año; [HttpOnly] (el [JavaScript] de la página no puede leerla); [SameSite=Lax] (no se envía en solicitudes POST provenientes de otros sitios).
El archivo [controllers/LanguageController.java]:
Analicemos este código:
- líneas 20–24: el controlador recibe [LocaleResolver] mediante inyección de dependencias;
- líneas 27–35: [GET /language/fr] almacena la selección en una cookie y luego redirige a la página de la que venía el usuario. Un idioma desconocido provoca un error 404 ([ResponseStatusException], vea el Ejemplo 21);
- línea 33: no creamos la cookie nosotros mismos; en su lugar, le pedimos a [LocaleResolver] que cambie el idioma, y este escribe la cookie con el nombre y las características especificados en [WebConfig]. [Locale.forLanguageTag("en")] crea el objeto [Locale] para el inglés;
- línea 34: [redirect:] solicita una redirección (vea el ejemplo 04);
- líneas 40–55: la página de origen la indica el encabezado [Referer], que el navegador agrega cuando se hace clic en un enlace. Conservamos solo la ruta y los parámetros ([getRawPath], [getRawQuery]: tal como aparecen en la dirección, sin decodificar). Redirigir a una URL completa tomada de la solicitud permitiría que un sitio malicioso cree un enlace que, tras pasar por nuestro sitio, envíe al usuario al sitio malicioso (una vulnerabilidad conocida como [open redirect]);
- líneas 45–49: una ruta que comienza con dos barras también se rechaza: el navegador interpretaría [//pirate.example/trap] como la dirección [http://pirate.example/trap], en otro sitio;
- líneas 51–54: sin el encabezado [Referer], [URI.create(null)] lanza una [NullPointerException]; una dirección no válida, una [IllegalArgumentException]. Ambas derivan de [RuntimeException]: esto lo lleva de vuelta a la página de inicio.
5.1.5. Las vistas
El archivo [templates/layout.html]:
- Línea 3: la plantilla (vea el Ejemplo 15) es un fragmento con dos parámetros: el título de la página y su contenido. El atributo [lang] de la página refleja el idioma seleccionado (útil para lectores de pantalla y correctores ortográficos): [#locale] es el idioma de la solicitud, y [#locale.language] es su código de dos letras;
- línea 7: el título de la página es una clave, proporcionada por la página y traducida por la plantilla: en [#{${title}}], la clave misma es el resultado de una expresión;
- línea 13: la barra de navegación, un fragmento de otro archivo.
El archivo [templates/fragments/navbar.html]:
- Líneas 4–5: dos textos traducidos. El texto escrito dentro de la etiqueta ([Home]) solo se muestra si el archivo se abre directamente en un navegador; [Thymeleaf] lo reemplaza por la traducción;
- línea 8: [th:with] define una variable local, [language], que puede utilizarse dentro de la etiqueta y de sus etiquetas hijas;
- Líneas 9-10: dos enlaces (cambiar el idioma no modifica ningún dato de la aplicación: basta con un GET), con el idioma actual resaltado: [th:classappend] agrega una clase CSS a las de la etiqueta.
El archivo [templates/pages/home.html]:
- línea 2: la página invoca la plantilla, usando la clave para su título y su contenido (la etiqueta [main]);
- línea 7: un parámetro, pasado como un par (nombre, valor);
- línea 9: la fecha se formatea primero con el bean [formats] y luego se pasa como el parámetro [date] al mensaje.
El archivo [templates/pages/products.html]:
- línea 11: el importe, formateado según el idioma;
- línea 15: un parámetro numérico: [#lists.size] indica el tamaño de la lista; [Translator] convierte el valor en una cadena ([String.valueOf]).
El archivo [controllers/PagesController.java]:
Las acciones no dependen del idioma: proporcionan los datos, mientras que las vistas los traducen y formatean. El precio es un [BigDecimal], y el tipo [Java] para números decimales exactos es adecuado para importes monetarios (línea 16). La fecha de la página de inicio es una fecha fija, el 23 de septiembre de 2026 (línea 22), y no la fecha actual: por lo tanto, los resultados que se muestran a continuación no dependen del día en que se ejecute el ejemplo.
5.1.6. Ejecución
En inglés (todavía sin cookie), en la URL http://localhost:5000/ y http://localhost:5000/products:


Un clic en un botón de idioma (aquí EN), simulado con [curl] (la opción [-H] agrega el encabezado [Referer] que el navegador habría enviado):
[CookieLocaleResolver] establece la cookie [language], con el valor [en], con las características solicitadas ([Max-Age] y [Expires] especifican ambas la duración, para navegadores antiguos y recientes, respectivamente). La redirección regresa a la página original ([Tomcat]; el servidor ha expandido la ruta [/products] a una dirección completa). Un clic en FR funciona de la misma manera (cookie [language=fr]): las páginas ahora están en francés:


Las fechas y los importes siguieron el cambio: “mercredi 23 septembre 2026”, “1 149,00 €”.
Un sitio malicioso que intente aprovechar nuestra redirección solo vería una página de nuestro sitio:
Un idioma no admitido:
La respuesta de error predeterminada de [Spring Boot]: JSON para [curl], una página HTML para un navegador. El capítulo 7 muestra cómo reemplazarla por una página propia.
Por último, recuerde que una cookie está bajo el control del cliente. Una cookie [language=de] creada manualmente es aceptada por [CookieLocaleResolver]: el texto sigue en inglés (el idioma predeterminado de [Translator]), pero la fecha se formatea en alemán:
(solo se muestran tres líneas de la página). No tiene mayor importancia: el usuario solo se engaña a sí mismo.
El caso de estudio procede exactamente de esta manera, con diccionarios más completos ([i18n/fr.json] y [i18n/en.json]): el mismo bean [messageSource], el mismo [CookieLocaleResolver], el mismo controlador [/language/{language}]. La única diferencia es que los mensajes de error generados por las capas de negocio y web también son claves, traducidas en el último momento por la vista.