Fusionar traducciones en la aplicación

Para fusionar las traducciones completas en tu proyecto, realiza las siguientes acciones

Usa el CLI de Angular para compilar una copia de los archivos distribuibles de tu proyecto
Usa la opción "localize" para reemplazar todos los mensajes i18n con las traducciones válidas y compilar una variante localizada de la aplicación. Una aplicación variante es una copia completa de los archivos distribuibles de tu aplicación traducida para una sola configuración regional.

Después de fusionar las traducciones, sirve cada copia distribuible de la aplicación usando detección de idioma del lado del servidor o subdirectorios diferentes.

ÚTIL: Para más información sobre cómo servir cada copia distribuible de la aplicación, consulta desplegar múltiples configuraciones regionales.

Para una traducción en tiempo de compilación de la aplicación, el proceso de compilación usa compilación por adelantado (AOT) para producir una aplicación pequeña, rápida y lista para ejecutarse.

ÚTIL: Para una explicación detallada del proceso de compilación, consulta Compilar y servir aplicaciones Angular. El proceso de compilación funciona con archivos de traducción en formato .xlf o en otro formato que Angular entienda, como .xtb. Para más información sobre formatos de archivos de traducción usados por Angular, consulta Cambiar el formato del archivo del idioma fuente

Para compilar una copia distribuible separada de la aplicación para cada configuración regional, define las configuraciones regionales en la configuración de compilación en el archivo angular.json de configuración de compilación del espacio de trabajo de tu proyecto.

Este método acorta el proceso de compilación al eliminar el requisito de realizar una compilación completa de la aplicación para cada configuración regional.

Para generar variantes de la aplicación para cada configuración regional, usa la opción "localize" en el archivo angular.json de configuración de compilación. Además, para compilar desde la línea de comandos, usa el comando build del CLI de Angular con la opción --localize.

ÚTIL: Opcionalmente, aplica opciones de compilación específicas para solo una configuración regional para una configuración personalizada.

Definir configuraciones regionales en la configuración de compilación

Usa la opción de proyecto i18n en el archivo angular.json de configuración de compilación del espacio de trabajo de tu proyecto para definir configuraciones regionales para un proyecto.

Las siguientes subopciones identifican el idioma fuente e indican al compilador dónde encontrar traducciones compatibles para el proyecto.

Subopción	Detalles
`sourceLocale`	La configuración regional que usas dentro del código fuente de la aplicación (`en-US` por defecto)
`locales`	Un mapa de identificadores de configuración regional a archivos de traducción

Ejemplo de `angular.json` para `en-US` y `fr`

Por ejemplo, el siguiente extracto de un archivo angular.json de configuración de compilación del espacio de trabajo establece la configuración regional de origen en en-US y proporciona la ruta al archivo de traducción de la configuración regional francesa (fr).

angular.json

{  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",  "version": 1,  "newProjectRoot": "projects",  "projects": {    "angular.io-example": {      "projectType": "application",      "root": "",      "sourceRoot": "src",      "prefix": "app",      "i18n": {        "sourceLocale": "en-US",        "locales": {          "fr": {            "translation": "src/locale/messages.fr.xlf",            "subPath": ""          }        }      },      "architect": {        "build": {          "builder": "@angular-devkit/build-angular:browser",          "options": {            "localize": true,            "outputPath": "dist",            "index": "src/index.html",            "main": "src/main.ts",            "polyfills": ["zone.js"],            "tsConfig": "tsconfig.app.json",            "assets": ["src/favicon.ico", "src/assets"],            "styles": ["src/styles.css"],            "scripts": [],            "i18nMissingTranslation": "error"          },          "configurations": {            "production": {              "budgets": [                {                  "type": "initial",                  "maximumWarning": "500kb",                  "maximumError": "1mb"                },                {                  "type": "anyComponentStyle",                  "maximumWarning": "2kb",                  "maximumError": "4kb"                }              ],              "outputHashing": "all"            },            "development": {              "localize": false,              "buildOptimizer": false,              "optimization": false,              "vendorChunk": true,              "extractLicenses": false,              "sourceMap": true,              "namedChunks": true            },            "fr": {              "localize": ["fr"]            }          },          "defaultConfiguration": "production"        },        "serve": {          "builder": "@angular-devkit/build-angular:dev-server",          "configurations": {            "production": {              "buildTarget": "angular.io-example:build:production"            },            "development": {              "buildTarget": "angular.io-example:build:development"            },            "fr": {              "buildTarget": "angular.io-example:build:development,fr"            }          },          "defaultConfiguration": "development"        },        "extract-i18n": {          "builder": "@angular-devkit/build-angular:extract-i18n",          "options": {            "buildTarget": "angular.io-example:build"          }        },        "test": {          "builder": "@angular-devkit/build-angular:karma",          "options": {            "polyfills": ["zone.js", "zone.js/testing"],            "tsConfig": "tsconfig.spec.json",            "assets": ["src/favicon.ico", "src/assets"],            "styles": ["src/styles.css"],            "scripts": []          }        },        "e2e": {          "builder": "@angular-devkit/build-angular:private-protractor",          "options": {            "protractorConfig": "e2e/protractor.conf.js",            "devServerTarget": "angular.io-example:serve:fr"          },          "configurations": {            "production": {              "devServerTarget": "angular.io-example:serve:production"            }          }        }      }    }  }}

Generar variantes de la aplicación para cada configuración regional

Para usar tu definición de configuraciones regionales en la configuración de compilación, usa la opción "localize" en el archivo angular.json para indicar al CLI qué configuraciones regionales generar para la compilación.

Establece "localize" en true para todas las configuraciones regionales definidas previamente en la configuración de compilación.
Establece "localize" en un array con un subconjunto de los identificadores de configuración regional definidos previamente para compilar solo esas versiones.
Establece "localize" en false para deshabilitar la localización y no generar versiones específicas por configuración regional.

ÚTIL: Se requiere compilación por adelantado (AOT) para localizar las plantillas de componentes.

Si cambiaste esta configuración, establece "aot" en true para usar AOT.

ÚTIL: Debido a las complejidades de despliegue de i18n y la necesidad de minimizar el tiempo de reconstrucción, el servidor de desarrollo solo admite localizar una sola configuración regional a la vez. Si configuras la opción "localize" en true, defines más de una configuración regional y usas ng serve, se producirá un error. Si deseas desarrollar con una configuración regional específica, establece la opción "localize" a una configuración regional específica. Por ejemplo, para francés (fr), especifica "localize": ["fr"].

El CLI carga y registra los datos de configuración regional, coloca cada versión generada en un directorio específico de configuración regional para mantenerla separada de otras versiones y ubica los directorios dentro del outputPath configurado para el proyecto. Para cada variante de aplicación, el atributo lang del elemento html se establece en la configuración regional. El CLI también ajusta el HREF base de HTML para cada versión de la aplicación agregando la configuración regional al baseHref configurado.

Establece la propiedad "localize" como una configuración compartida para heredarla efectivamente en todas las configuraciones. Además, establece la propiedad para anular otras configuraciones.

Ejemplo de `angular.json` que incluye todas las configuraciones regionales de la compilación

El siguiente ejemplo muestra la opción "localize" establecida en true en el archivo angular.json de configuración de compilación del espacio de trabajo, de modo que se compilen todas las configuraciones regionales definidas en la configuración de compilación.

angular.json

{  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",  "version": 1,  "newProjectRoot": "projects",  "projects": {    "angular.io-example": {      "projectType": "application",      "root": "",      "sourceRoot": "src",      "prefix": "app",      "i18n": {        "sourceLocale": "en-US",        "locales": {          "fr": {            "translation": "src/locale/messages.fr.xlf",            "subPath": ""          }        }      },      "architect": {        "build": {          "builder": "@angular-devkit/build-angular:browser",          "options": {            "localize": true,            "outputPath": "dist",            "index": "src/index.html",            "main": "src/main.ts",            "polyfills": ["zone.js"],            "tsConfig": "tsconfig.app.json",            "assets": ["src/favicon.ico", "src/assets"],            "styles": ["src/styles.css"],            "scripts": [],            "i18nMissingTranslation": "error"          },          "configurations": {            "production": {              "budgets": [                {                  "type": "initial",                  "maximumWarning": "500kb",                  "maximumError": "1mb"                },                {                  "type": "anyComponentStyle",                  "maximumWarning": "2kb",                  "maximumError": "4kb"                }              ],              "outputHashing": "all"            },            "development": {              "localize": false,              "buildOptimizer": false,              "optimization": false,              "vendorChunk": true,              "extractLicenses": false,              "sourceMap": true,              "namedChunks": true            },            "fr": {              "localize": ["fr"]            }          },          "defaultConfiguration": "production"        },        "serve": {          "builder": "@angular-devkit/build-angular:dev-server",          "configurations": {            "production": {              "buildTarget": "angular.io-example:build:production"            },            "development": {              "buildTarget": "angular.io-example:build:development"            },            "fr": {              "buildTarget": "angular.io-example:build:development,fr"            }          },          "defaultConfiguration": "development"        },        "extract-i18n": {          "builder": "@angular-devkit/build-angular:extract-i18n",          "options": {            "buildTarget": "angular.io-example:build"          }        },        "test": {          "builder": "@angular-devkit/build-angular:karma",          "options": {            "polyfills": ["zone.js", "zone.js/testing"],            "tsConfig": "tsconfig.spec.json",            "assets": ["src/favicon.ico", "src/assets"],            "styles": ["src/styles.css"],            "scripts": []          }        },        "e2e": {          "builder": "@angular-devkit/build-angular:private-protractor",          "options": {            "protractorConfig": "e2e/protractor.conf.js",            "devServerTarget": "angular.io-example:serve:fr"          },          "configurations": {            "production": {              "devServerTarget": "angular.io-example:serve:production"            }          }        }      }    }  }}

Compilar desde la línea de comandos

Además, usa la opción --localize con el comando ng build y tu configuración production existente. El CLI compila todas las configuraciones regionales definidas en la configuración de compilación. Si estableces las configuraciones regionales en la configuración de compilación, es similar a cuando estableces la opción "localize" en true.

ÚTIL: Para más información sobre cómo establecer las configuraciones regionales, consulta Generar variantes de la aplicación para cada configuración regional.

ng add @angular/localizeng extract-i18nng extract-i18n --output-path src/localeng extract-i18n --format=xlfng extract-i18n --format=xlf2ng extract-i18n --format=xmbng extract-i18n --format=jsonng extract-i18n --format=arbng extract-i18n --out-file source.xlfng build --localizeng serve --configuration=frng build --configuration=production,fr

Aplicar opciones específicas de compilación para solo una configuración regional

Para aplicar opciones específicas de compilación a solo una configuración regional, especifica una sola configuración regional para crear una configuración personalizada específica.

IMPORTANTE: Usa el servidor de desarrollo del CLI de Angular (ng serve) con una sola configuración regional.

Ejemplo de compilación para francés

El siguiente ejemplo muestra una configuración personalizada específica para una sola configuración regional.

angular.json

{  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",  "version": 1,  "newProjectRoot": "projects",  "projects": {    "angular.io-example": {      "projectType": "application",      "root": "",      "sourceRoot": "src",      "prefix": "app",      "i18n": {        "sourceLocale": "en-US",        "locales": {          "fr": {            "translation": "src/locale/messages.fr.xlf",            "subPath": ""          }        }      },      "architect": {        "build": {          "builder": "@angular-devkit/build-angular:browser",          "options": {            "localize": true,            "outputPath": "dist",            "index": "src/index.html",            "main": "src/main.ts",            "polyfills": ["zone.js"],            "tsConfig": "tsconfig.app.json",            "assets": ["src/favicon.ico", "src/assets"],            "styles": ["src/styles.css"],            "scripts": [],            "i18nMissingTranslation": "error"          },          "configurations": {            "production": {              "budgets": [                {                  "type": "initial",                  "maximumWarning": "500kb",                  "maximumError": "1mb"                },                {                  "type": "anyComponentStyle",                  "maximumWarning": "2kb",                  "maximumError": "4kb"                }              ],              "outputHashing": "all"            },            "development": {              "localize": false,              "buildOptimizer": false,              "optimization": false,              "vendorChunk": true,              "extractLicenses": false,              "sourceMap": true,              "namedChunks": true            },            "fr": {              "localize": ["fr"]            }          },          "defaultConfiguration": "production"        },        "serve": {          "builder": "@angular-devkit/build-angular:dev-server",          "configurations": {            "production": {              "buildTarget": "angular.io-example:build:production"            },            "development": {              "buildTarget": "angular.io-example:build:development"            },            "fr": {              "buildTarget": "angular.io-example:build:development,fr"            }          },          "defaultConfiguration": "development"        },        "extract-i18n": {          "builder": "@angular-devkit/build-angular:extract-i18n",          "options": {            "buildTarget": "angular.io-example:build"          }        },        "test": {          "builder": "@angular-devkit/build-angular:karma",          "options": {            "polyfills": ["zone.js", "zone.js/testing"],            "tsConfig": "tsconfig.spec.json",            "assets": ["src/favicon.ico", "src/assets"],            "styles": ["src/styles.css"],            "scripts": []          }        },        "e2e": {          "builder": "@angular-devkit/build-angular:private-protractor",          "options": {            "protractorConfig": "e2e/protractor.conf.js",            "devServerTarget": "angular.io-example:serve:fr"          },          "configurations": {            "production": {              "devServerTarget": "angular.io-example:serve:production"            }          }        }      }    }  }}

Pasa esta configuración a los comandos ng serve o ng build. El siguiente ejemplo de código muestra cómo servir el archivo de idioma francés.

ng add @angular/localizeng extract-i18nng extract-i18n --output-path src/localeng extract-i18n --format=xlfng extract-i18n --format=xlf2ng extract-i18n --format=xmbng extract-i18n --format=jsonng extract-i18n --format=arbng extract-i18n --out-file source.xlfng build --localizeng serve --configuration=frng build --configuration=production,fr

Para compilaciones de producción, usa composición de configuraciones para ejecutar ambas configuraciones.

ng add @angular/localizeng extract-i18nng extract-i18n --output-path src/localeng extract-i18n --format=xlfng extract-i18n --format=xlf2ng extract-i18n --format=xmbng extract-i18n --format=jsonng extract-i18n --format=arbng extract-i18n --out-file source.xlfng build --localizeng serve --configuration=frng build --configuration=production,fr

angular.json

{  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",  "version": 1,  "newProjectRoot": "projects",  "projects": {    "angular.io-example": {      "projectType": "application",      "root": "",      "sourceRoot": "src",      "prefix": "app",      "i18n": {        "sourceLocale": "en-US",        "locales": {          "fr": {            "translation": "src/locale/messages.fr.xlf",            "subPath": ""          }        }      },      "architect": {        "build": {          "builder": "@angular-devkit/build-angular:browser",          "options": {            "localize": true,            "outputPath": "dist",            "index": "src/index.html",            "main": "src/main.ts",            "polyfills": ["zone.js"],            "tsConfig": "tsconfig.app.json",            "assets": ["src/favicon.ico", "src/assets"],            "styles": ["src/styles.css"],            "scripts": [],            "i18nMissingTranslation": "error"          },          "configurations": {            "production": {              "budgets": [                {                  "type": "initial",                  "maximumWarning": "500kb",                  "maximumError": "1mb"                },                {                  "type": "anyComponentStyle",                  "maximumWarning": "2kb",                  "maximumError": "4kb"                }              ],              "outputHashing": "all"            },            "development": {              "localize": false,              "buildOptimizer": false,              "optimization": false,              "vendorChunk": true,              "extractLicenses": false,              "sourceMap": true,              "namedChunks": true            },            "fr": {              "localize": ["fr"]            }          },          "defaultConfiguration": "production"        },        "serve": {          "builder": "@angular-devkit/build-angular:dev-server",          "configurations": {            "production": {              "buildTarget": "angular.io-example:build:production"            },            "development": {              "buildTarget": "angular.io-example:build:development"            },            "fr": {              "buildTarget": "angular.io-example:build:development,fr"            }          },          "defaultConfiguration": "development"        },        "extract-i18n": {          "builder": "@angular-devkit/build-angular:extract-i18n",          "options": {            "buildTarget": "angular.io-example:build"          }        },        "test": {          "builder": "@angular-devkit/build-angular:karma",          "options": {            "polyfills": ["zone.js", "zone.js/testing"],            "tsConfig": "tsconfig.spec.json",            "assets": ["src/favicon.ico", "src/assets"],            "styles": ["src/styles.css"],            "scripts": []          }        },        "e2e": {          "builder": "@angular-devkit/build-angular:private-protractor",          "options": {            "protractorConfig": "e2e/protractor.conf.js",            "devServerTarget": "angular.io-example:serve:fr"          },          "configurations": {            "production": {              "devServerTarget": "angular.io-example:serve:production"            }          }        }      }    }  }}

Reportar traducciones faltantes

Cuando falta una traducción, la compilación tiene éxito pero genera una advertencia como Missing translation for message "{translation_text}". Para configurar el nivel de advertencia que genera el compilador de Angular, especifica uno de los siguientes niveles.

Nivel de advertencia	Detalles	Salida
`error`	Lanza un error y la compilación falla	n/a
`ignore`	No hace nada	n/a
`warning`	Muestra la advertencia predeterminada en la consola o shell	`Missing translation for message "{translation_text}"`

Especifica el nivel de advertencia en la sección options para el objetivo build de tu archivo angular.json de configuración de compilación del espacio de trabajo.

Ejemplo de advertencia `error` en `angular.json`

El siguiente ejemplo muestra cómo establecer el nivel de advertencia en error.

angular.json

{  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",  "version": 1,  "newProjectRoot": "projects",  "projects": {    "angular.io-example": {      "projectType": "application",      "root": "",      "sourceRoot": "src",      "prefix": "app",      "i18n": {        "sourceLocale": "en-US",        "locales": {          "fr": {            "translation": "src/locale/messages.fr.xlf",            "subPath": ""          }        }      },      "architect": {        "build": {          "builder": "@angular-devkit/build-angular:browser",          "options": {            "localize": true,            "outputPath": "dist",            "index": "src/index.html",            "main": "src/main.ts",            "polyfills": ["zone.js"],            "tsConfig": "tsconfig.app.json",            "assets": ["src/favicon.ico", "src/assets"],            "styles": ["src/styles.css"],            "scripts": [],            "i18nMissingTranslation": "error"          },          "configurations": {            "production": {              "budgets": [                {                  "type": "initial",                  "maximumWarning": "500kb",                  "maximumError": "1mb"                },                {                  "type": "anyComponentStyle",                  "maximumWarning": "2kb",                  "maximumError": "4kb"                }              ],              "outputHashing": "all"            },            "development": {              "localize": false,              "buildOptimizer": false,              "optimization": false,              "vendorChunk": true,              "extractLicenses": false,              "sourceMap": true,              "namedChunks": true            },            "fr": {              "localize": ["fr"]            }          },          "defaultConfiguration": "production"        },        "serve": {          "builder": "@angular-devkit/build-angular:dev-server",          "configurations": {            "production": {              "buildTarget": "angular.io-example:build:production"            },            "development": {              "buildTarget": "angular.io-example:build:development"            },            "fr": {              "buildTarget": "angular.io-example:build:development,fr"            }          },          "defaultConfiguration": "development"        },        "extract-i18n": {          "builder": "@angular-devkit/build-angular:extract-i18n",          "options": {            "buildTarget": "angular.io-example:build"          }        },        "test": {          "builder": "@angular-devkit/build-angular:karma",          "options": {            "polyfills": ["zone.js", "zone.js/testing"],            "tsConfig": "tsconfig.spec.json",            "assets": ["src/favicon.ico", "src/assets"],            "styles": ["src/styles.css"],            "scripts": []          }        },        "e2e": {          "builder": "@angular-devkit/build-angular:private-protractor",          "options": {            "protractorConfig": "e2e/protractor.conf.js",            "devServerTarget": "angular.io-example:serve:fr"          },          "configurations": {            "production": {              "devServerTarget": "angular.io-example:serve:production"            }          }        }      }    }  }}

ÚTIL: Cuando compilas tu proyecto Angular en una aplicación Angular, las instancias del atributo i18n se reemplazan con instancias de la cadena de mensaje etiquetada $localize. Esto significa que tu aplicación Angular se traduce después de la compilación. Esto también significa que puedes crear versiones localizadas de tu aplicación Angular sin recompilar todo tu proyecto Angular para cada configuración regional.

Cuando traduces tu aplicación Angular, la transformación de traducción reemplaza y reordena las partes (cadenas estáticas y expresiones) de la cadena literal de plantilla con cadenas de una colección de traducciones. Para más información, consulta $localize.

TL;DR: Compila una vez, luego traduce para cada configuración regional.