Skip to main content

Localización de módulos

Cada módulo trae sus propios textos (nombres, etiquetas, menús, permisos, mensajes) como recursos de idioma en archivos XML. Al instalar el módulo, esos recursos se importan a la base de datos; al desinstalarlo, se eliminan. En tiempo de ejecución se consultan por el sistema de localización del núcleo (ver Localización).

Archivos de recursos​

Los recursos van en la carpeta Localizacion/ del módulo, con un archivo por cultura siguiendo el patrón recursos.{cultura}.xml. Por ejemplo, para el español de Perú:

Crono.Facturacion/
└── Localizacion/
    └── recursos.es-pe.xml

La estructura del archivo es:

<Idioma Nombre="Español" EsPredeterminado="false" EsDerechaAIzquierda="false">
  <RecursoLocal Nombre="Complementos.NombreDescriptivo.Crono.Facturacion" ClaveRaizAgregar="false">
    <Valor>Facturación electrónica</Valor>
  </RecursoLocal>
  <RecursoLocal Nombre="Complementos.Descripcion.Crono.Facturacion" ClaveRaizAgregar="false">
    <Valor>Emisión de comprobantes de pago electrónicos ante SUNAT...</Valor>
  </RecursoLocal>
  <RecursoLocal Nombre="MenuConfiguracion">
    <Valor>Facturación electrónica</Valor>
  </RecursoLocal>
  <RecursoLocal Nombre="PestaniaConexion">
    <Valor>Conexión SUNAT</Valor>
  </RecursoLocal>
</Idioma>

La clave raíz de recursos​

El campo ClaveRaizRecurso del modulo.json es el prefijo que se antepone a los nombres de recurso del módulo. Por ejemplo, con:

"ClaveRaizRecurso": "Complementos.Contabilidad.Facturacion"

un recurso declarado como MenuConfiguracion se registra realmente como Complementos.Contabilidad.Facturacion.MenuConfiguracion. Esto evita colisiones entre módulos y agrupa sus textos bajo un espacio de nombres propio.

El atributo ClaveRaizAgregar="false" en un <RecursoLocal> indica que no se anteponga la clave raíz a ese recurso concreto: se usa para nombres absolutos que deben ser globales, como el nombre y la descripción del propio módulo (Complementos.NombreDescriptivo.{NombreSistema}, Complementos.Descripcion.{NombreSistema}) o el nombre visible de sus permisos (Modulos.Permisos.NombreMostrar.{...}).

Importar y eliminar recursos​

La importación y eliminación se hacen en las rutinas del módulo. ModuloBase ofrece los ayudantes:

public override async Task InstalarAsync(ModuloInstalacionContexto contexto)
{
    await ImportarIdiomaRecursosAsync();   // lee los recursos.{cultura}.xml y los guarda en BD
    await base.InstalarAsync(contexto);
}

public override async Task DesinstalarAsync()
{
    await EliminarIdiomaRecursosAsync();   // borra los recursos cuya clave empieza por ClaveRaizRecurso
    await base.DesinstalarAsync();
}

Internamente, ImportarIdiomaRecursosAsync() resuelve el administrador de recursos XML y lo importa a partir del descriptor del módulo; EliminarIdiomaRecursosAsync() elimina las cadenas cuyo nombre comienza por la ClaveRaizRecurso del módulo.

Usar los textos​

En las vistas y modelos se consumen igual que cualquier recurso del núcleo: con el localizador (T[...]) en el código y con atributos de visualización localizada en los modelos. Al referenciar un recurso del módulo se usa su nombre completo (con la clave raíz), salvo los recursos marcados como absolutos.

info

Si añades una nueva cultura basta con incluir otro archivo recursos.{cultura}.xml en Localizacion/. El sistema elige el más específico disponible para el idioma activo del usuario.