Mesclar traduções na aplicação

Para mesclar as traduções completas em seu projeto, complete as seguintes ações

Use o Angular CLI para buildar uma cópia dos arquivos distribuíveis do seu projeto
Use a opção "localize" para substituir todas as mensagens i18n com as traduções válidas e buildar uma aplicação de variante localizada. Uma aplicação de variante é uma cópia completa dos arquivos distribuíveis da sua aplicação traduzida para um único locale.

Depois de mesclar as traduções, sirva cada cópia distribuível da aplicação usando detecção de idioma do lado do servidor ou subdiretórios diferentes.

HELPFUL: Para mais informações sobre como servir cada cópia distribuível da aplicação, veja fazer deploy de múltiplos locales.

Para uma tradução em tempo de compilação da aplicação, o processo de build usa compilação ahead-of-time (AOT) para produzir uma aplicação pequena, rápida e pronta para executar.

HELPFUL: Para uma explicação detalhada do processo de build, veja Building and serving Angular apps. O processo de build funciona para arquivos de tradução no formato .xlf ou em outro formato que o Angular entenda, como .xtb. Para mais informações sobre formatos de arquivo de tradução usados pelo Angular, veja Alterar o formato do arquivo de idioma fonte

Para buildar uma cópia distribuível separada da aplicação para cada locale, defina os locales na configuração de build no arquivo de configuração de build do workspace angular.json do seu projeto.

Este método encurta o processo de build removendo o requisito de realizar um build completo da aplicação para cada locale.

Para gerar variantes de aplicação para cada locale, use a opção "localize" no arquivo de configuração de build do workspace angular.json. Além disso, para buildar da linha de comando, use o comando build do Angular CLI com a opção --localize.

HELPFUL: Opcionalmente, aplique opções de build específicas para apenas um locale para uma configuração de locale personalizada.

Definir locales na configuração de build

Use a opção de projeto i18n no arquivo de configuração de build do workspace angular.json do seu projeto para definir locales para um projeto.

As seguintes sub-opções identificam o idioma fonte e informam ao compilador onde encontrar traduções suportadas para o projeto.

Sub-opção	Detalhes
`sourceLocale`	O locale que você usa dentro do código fonte da aplicação (`en-US` por padrão)
`locales`	Um mapa de identificadores de locale para arquivos de tradução

Exemplo de `angular.json` para `en-US` e `fr`

Por exemplo, o seguinte trecho de um arquivo de configuração de build do workspace angular.json define o locale fonte como en-US e fornece o caminho para o arquivo de tradução do locale francês (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"            }          }        }      }    }  }}

Gerar variantes de aplicação para cada locale

Para usar sua definição de locale na configuração de build, use a opção "localize" no arquivo de configuração de build do workspace angular.json para informar ao CLI quais locales gerar para a configuração de build.

Defina "localize" como true para todos os locales previamente definidos na configuração de build.
Defina "localize" como um array de um subconjunto dos identificadores de locale previamente definidos para buildar apenas aquelas versões de locale.
Defina "localize" como false para desabilitar a localização e não gerar nenhuma versão específica de locale.

HELPFUL: Compilação ahead-of-time (AOT) é necessária para localizar templates de components.

Se você alterou esta configuração, defina "aot" como true para usar AOT.

HELPFUL: Devido às complexidades de deployment do i18n e à necessidade de minimizar o tempo de rebuild, o servidor de desenvolvimento suporta apenas localizar um único locale por vez. Se você definir a opção "localize" como true, definir mais de um locale e usar ng serve; então um erro ocorre. Se você quiser desenvolver contra um locale específico, defina a opção "localize" para um locale específico. Por exemplo, para francês (fr), especifique "localize": ["fr"].

O CLI carrega e registra os dados de locale, coloca cada versão gerada em um diretório específico de locale para mantê-la separada de outras versões de locale, e coloca os diretórios dentro do outputPath configurado para o projeto. Para cada variante de aplicação, o atributo lang do elemento html é definido como o locale. O CLI também ajusta o HREF base HTML para cada versão da aplicação adicionando o locale ao baseHref configurado.

Defina a propriedade "localize" como uma configuração compartilhada para efetivamente herdar para todas as configurações. Além disso, defina a propriedade para sobrescrever outras configurações.

Exemplo de `angular.json` incluindo todos os locales do build

O exemplo a seguir exibe a opção "localize" definida como true no arquivo de configuração de build do workspace angular.json, de modo que todos os locales definidos na configuração de build sejam buildados.

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"            }          }        }      }    }  }}

Buildar da linha de comando

Além disso, use a opção --localize com o comando ng build e sua configuração production existente. O CLI builda todos os locales definidos na configuração de build. Se você definir os locales na configuração de build, é similar a quando você define a opção "localize" como true.

HELPFUL: Para mais informações sobre como definir os locales, veja Gerar variantes de aplicação para cada locale.

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 opções de build específicas para apenas um locale

Para aplicar opções de build específicas a apenas um locale, especifique um único locale para criar uma configuração específica de locale personalizada.

IMPORTANT: Use o servidor de desenvolvimento Angular CLI (ng serve) com apenas um único locale.

Exemplo de build para francês

O exemplo a seguir exibe uma configuração específica de locale personalizada usando um único locale.

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"            }          }        }      }    }  }}

Passe esta configuração para os comandos ng serve ou ng build. O exemplo de código a seguir exibe como servir o arquivo 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 builds de produção, use composição de configuração para executar ambas as configurações.

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 traduções ausentes

Quando uma tradução está ausente, o build é bem-sucedido mas gera um aviso como Missing translation for message "{translation_text}". Para configurar o nível de aviso que é gerado pelo compilador Angular, especifique um dos seguintes níveis.

Nível de aviso	Detalhes	Saída
`error`	Lançar um erro e o build falha	n/a
`ignore`	Não fazer nada	n/a
`warning`	Exibe o aviso padrão no console ou shell	`Missing translation for message "{translation_text}"`

Especifique o nível de aviso na seção options para o target build do seu arquivo de configuração de build do workspace angular.json.

Exemplo de aviso `error` no `angular.json`

O exemplo a seguir exibe como definir o nível de aviso como 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"            }          }        }      }    }  }}

HELPFUL: Quando você compila seu projeto Angular em uma aplicação Angular, as instâncias do atributo i18n são substituídas com instâncias da tagged message string $localize. Isso significa que sua aplicação Angular é traduzida após a compilação. Isso também significa que você pode criar versões localizadas da sua aplicação Angular sem recompilar todo o seu projeto Angular para cada locale.

Quando você traduz sua aplicação Angular, a transformação de tradução substitui e reordena as partes (strings estáticas e expressões) da template literal string com strings de uma coleção de traduções. Para mais informações, veja $localize.

TL;DR: Compile uma vez, depois traduza para cada locale.