Upgrade Umbraco 13 to 16 Localization es la tercera entrega de una serie sobre tareas habituales al actualizar proyectos de Umbraco desde la versión 13 a la 16. En este artículo te explico cómo adaptar la localización del backoffice, los cambios en la localización del backend en .NET y cómo usar localización en tus extensiones del backoffice, todo en clave práctica para que tus editores y usuarios trabajen con una experiencia multilingüe impecable. En Q2BSTUDIO, empresa de desarrollo de software y aplicaciones a medida, especialistas en inteligencia artificial, ciberseguridad y servicios cloud, te acompañamos en todo el proceso para que tu actualización sea segura, eficiente y preparada para escalar.
Localización del backoffice UI Localization
La idea general se mantiene entre Umbraco 13 y 16. Sigues definiendo claves y valores localizados por idioma, pero ahora el backoffice funciona como un sistema de extensiones. En Umbraco 13 las traducciones del backoffice se definían en archivos XML y se cargaban por convención. En Umbraco 16 las traducciones del backoffice se escriben en JavaScript y se registran mediante un manifiesto de extensión. Esto te da mayor flexibilidad y te permite añadir lógica en tiempo de carga, reutilizar claves y trabajar con argumentos dinámicos.
Cómo migrar tus archivos de idioma del backoffice
Primero convierte cada archivo XML a su equivalente en JavaScript manteniendo los mismos alias de área y claves. Los archivos pueden tener el nombre y la ubicación que prefieras, ya no dependen de una carpeta concreta, pero deben registrarse en un manifiesto. Crea o actualiza tu umbraco-package.json y añade una entrada de tipo localization por cada idioma, indicando la cultura por ejemplo en, dk y la ruta al archivo JS. Tras registrarlos, las traducciones del backoffice vuelven a funcionar con normalidad.
Ajuste importante en descripciones de propiedades
En Umbraco 16 las descripciones de propiedades pasan por el pipeline de Umbraco Flavoured Markdown. Para que una clave se resuelva correctamente en una descripción, envuélvela entre llaves. Si la pones tal cual, no se traducirá. Al usar llaves, el sistema interpreta y localiza la clave antes de renderizar el texto final.
Localización en el backend .NET
El antiguo servicio ILocalizationService desaparece por exceso de responsabilidades. Se sustituye por dos servicios más claros y específicos. Para la gestión de idiomas de contenido utiliza ILanguageService. Para gestionar el diccionario y sus entradas utiliza IDictionaryService. Por su parte, ILocalizeTextService sigue existiendo y continúa leyendo archivos XML para resolver claves en el backend C#, por lo que puedes mantener tus recursos de .NET en ese formato.
Localización en extensiones del backoffice
En los manifiestos de extensiones puedes referenciar claves de localización directamente, por ejemplo en etiquetas, títulos y descripciones de dashboards, menús y vistas. Si creas web components con la base de Umbraco y Lit, al heredar de UmbLitElement o aplicar UmbElementMixin sobre LitElement tendrás un helper de localización disponible dentro del componente. Además, puedes usar elementos auxiliares de localización en tus plantillas para resolver claves de forma declarativa. El nuevo modelo basado en JavaScript te permite añadir argumentos y placeholders a las traducciones. Con ello puedes resolver singular y plural en una misma clave o inyectar valores dinámicos como conteos, nombres de usuario o fechas, manteniendo una única fuente de verdad por idioma.
Buenas prácticas para tu migración
Mantén una nomenclatura coherente para áreas y claves a lo largo del proyecto. Centraliza todas las claves del backoffice en tus archivos de extensión y documenta su uso. Revisa las descripciones de propiedades y actualízalas al formato con llaves. Aprovecha argumentos para evitar duplicar claves por singular y plural. Valida la carga de extensiones y culturas en entornos previos a producción.
Cómo te ayuda Q2BSTUDIO
Somos expertos en modernizar soluciones sobre Umbraco y en integrar buenas prácticas de localización para equipos editoriales internacionales. Si necesitas un partner para aplicaciones a medida y software a medida con foco en rendimiento, seguridad y escalabilidad, visita nuestra página de desarrollo de aplicaciones y software multiplataforma. Además, utilizamos inteligencia artificial para acelerar conversiones de archivos y validar consistencia de claves entre idiomas, reduciendo errores y tiempos de despliegue. Descubre cómo aplicamos IA para empresas, agentes IA y automatización semántica en inteligencia artificial.
Beneficios clave tras actualizar a Umbraco 16
Backoffice más flexible y extensible al usar JavaScript y manifiestos. Mejor separación de responsabilidades en el backend al reemplazar ILocalizationService por ILanguageService e IDictionaryService. Soporte nativo para argumentos y placeholders en localizaciones del backoffice. Descripciones de propiedades con renderizado consistente gracias a Umbraco Flavoured Markdown. Menor fricción para equipos de contenido y menor deuda técnica para el equipo de desarrollo.
Resumen y próximos pasos
Convierte tus archivos XML del backoffice a JavaScript, regístralos en el manifiesto de extensiones y ajusta las descripciones de propiedades con llaves. En el backend, migra a ILanguageService e IDictionaryService y conserva ILocalizeTextService para recursos XML. Finalmente, actualiza tus extensiones para aprovechar claves de localización en manifiestos y componentes, incorporando argumentos cuando tenga sentido. Si buscas acelerar la migración, reforzar la ciberseguridad y preparar tu infraestructura para crecimiento con servicios cloud AWS y Azure, desde Q2BSTUDIO te ayudamos de punta a punta. Integramos ciberseguridad, servicios cloud aws y azure, inteligencia de negocio con Power BI, servicios inteligencia de negocio y automatización de procesos para que tu plataforma sea robusta, escalable y lista para el futuro.