Una práctica instrucción paso a paso sobre cómo ajustar la localización dinámica (la capacidad de seleccionar idiomas) en una aplicación web Angular 4+ usando @ ngx-translate / core .
En principio, puede encontrar publicaciones sobre un tema similar, la documentación de esta biblioteca puede ser suficiente, pero quería sistematizar esta instrucción para una aplicación más conveniente. Este marcador está en la alcancía de un desarrollador angular novato. Al final del artículo hay un enlace a un repositorio abierto con un ejemplo.
¿Por qué exactamente ngx-translate
Quiero hacer una reserva de inmediato, esta es una instrucción para usar una biblioteca específica. No hablaremos de alternativas, que el angular tiene su propia localización i18n. Aunque solo sea porque con un cambio dinámico de idioma hay preguntas.
¿Qué obtenemos en la salida?
- Aplicación angular, en la carpeta
assets/locale hay archivos *.json con claves y sus valores localizados, un archivo para cada idioma admitido en la aplicación web. - Cambio de idioma dinámico
- Almacenar claves en una estructura de objeto, es decir, tener algo como esto:
// en.json { Common: { Yes: "Yes" } }
Esto le permitirá agrupar claves / valores y de alguna manera organizar un archivo json con localización. Para proyectos grandes es bastante útil.
- Mínima automatización y comprobación de tontos. ¿Qué pasa si olvidó agregar la clave en json?
- Aplicación de localización tanto en plantillas html como en código ts
Personalizar
Creamos o tomamos un proyecto angular listo. La versión del angular es 4+, pero es mejor, por supuesto, lo más fresca posible.
Instale las bibliotecas necesarias:
npm install @ngx-translate/core --save npm install @ngx-translate/http-loader --save @biesbjerg/ngx-translate-extract --saveDev
La @ngx-translate/http-loader es necesaria para que podamos leer los datos de localización de los archivos *.json . Puede vivir sin él, pero luego tendrá que escribir el almacenamiento y la carga de los datos de localización de forma completamente independiente. Este enfoque es adecuado para aquellos que tienen datos de localización (o simplemente todos los textos traducidos) ya almacenados en algún lugar.
La @biesbjerg/ngx-translate-extract es opcional, pero bastante útil. Le permite recopilar claves de localización olvidadas por código de aplicación y actualizar archivos de localización. Usarlo es muy conveniente para procesar este escenario: agregue un nuevo idioma y simplemente ejecute el comando desde esta biblioteca. Como resultado, el archivo vacío para el nuevo idioma se rellenará con toda la estructura de las claves y algunos valores predeterminados. Un ejemplo estará debajo.
- Importe la biblioteca en el módulo principal:
@NgModule({ imports: [ TranslateModule.forRoot({ loader: { provide: TranslateLoader, useFactory: HttpLoaderFactory, deps: [HttpClient], }, useDefaultLang: false, }) ], }) export class AppModule { }
El HttpLoaderFactory presente en la HttpLoaderFactory la biblioteca, se puede describir directamente en el mismo archivo, es de tamaño modesto.
export function HttpLoaderFactory(http: HttpClient): TranslateLoader { return new TranslateHttpLoader(http, './assets/locale/', '.json'); }
Aquí es donde indicamos la ruta a los archivos de localización. Si se almacenan de alguna manera por separado, o incluso de manera diferente en diferentes entornos, cambie este código para usar environment.ts por ejemplo.
- En principio, esto es suficiente para la configuración básica, pero tomaremos otro paso adicional: manejo de errores cuando no se encuentre la clave.
Para hacer esto, agregue un campo más a la configuración (inmediatamente después de especificar el cargador):
missingTranslationHandler: { provide: MissingTranslationHandler, useClass: MissingTranslationService },
Y, por supuesto, debe crear la implementación de este controlador en un archivo separado:
export class MissingTranslationService implements MissingTranslationHandler { handle(params: MissingTranslationHandlerParams) { return `WARN: '${params.key}' is missing in '${params.translateService.currentLang}' locale`; } }
- Agregar almacenamiento de idiomas disponibles. En el caso simple, es conveniente ponerlos en su
environment.ts
locales: ['en', 'ru'], defaultLocale: 'en',
- Para que el servicio comience a funcionar, debe inicializarse en el archivo AppComponent al cargar la aplicación:
@Component({...}) export class AppComponent implements OnInit { constructor(private translateService: TranslateService) {} ngOnInit(): void { this.translateService.use(environment.defaultLocale); } }
- Agregue los archivos
en.json y ru.json (de acuerdo con lo que se indica en la lista de idiomas disponibles). Agregue un campo base para que sea json válido.
Cuando se toman estos pasos, el servicio comenzará a funcionar.
Utilizamos el servicio
Marcado HTML
Todo es simple aquí. La biblioteca ofrece translate tuberías, solo la aplicamos en el marcado de ciertas claves.
<label>{{ 'LANGUAGES.TITLE' | translate }}</label>
Tenga en cuenta que uso las propiedades adjuntas aquí, la estructura json de la que hablé al principio.
Los parámetros también son compatibles, mírelos por favor en la documentación @ ngx-translate / core . Usando parámetros, puede implementar algo como la interpolación de cadenas.
En código de componente
this.translateService.get(['KEY1', 'KEY2'])) .subscribe(translations => { console.log(translations['KEY1']) console.log(translations['KEY2']) });
Esta es una forma confiable si eres normal con Observable y RxJs.
Si no, hay una manera:
this.translateService.instant('Key')
Este método funciona bien, pero en la etapa de inicialización de la aplicación (por ejemplo, ngOnInit AppComponent) es posible que los datos aún no se hayan cargado. Ten cuidado
Soporte para archivos .json
Al final, quiero mostrar cómo usar la utilidad ngx-translate-extract . Simplemente ejecute el comando ngx-translate-extract -i ./src -o src/assets/locale/*.json --sort --format namespaced-json en la consola. Este comando iniciará el análisis de archivos de aplicación, marcado y código de código de tiempo. Todas las claves encontradas en el marcado y otros códigos caerán en .json para todos los idiomas, las claves existentes y sus valores permanecerán intactos, excepto que el orden puede cambiar.
Por conveniencia, estoy agregando esto como un script en package.json
"scripts": { "ng": "ng", "start": "ng serve", "update-locale": "ngx-translate-extract -i ./src -o src/assets/locale/*.json --sort --format namespaced-json" },
Todo lo que describí se puede encontrar ensamblado en un repositorio abierto: valentinkononov / ngx-translate-angular
¡Espero que el material sea útil! ¡Escriba código con gusto, elija bibliotecas convenientes y haga proyectos útiles!