angular-cli icon indicating copy to clipboard operation
angular-cli copied to clipboard

i18n support in Angular libraries

Open multimike77 opened this issue 4 years ago • 33 comments

🐞 Bug report

Command (mark with an x)

  • [ ] new
  • [ ] build
  • [ ] serve
  • [ ] test
  • [ ] e2e
  • [ ] generate
  • [ ] add
  • [ ] update
  • [ ] lint
  • [x] xi18n
  • [ ] run
  • [ ] config
  • [ ] help
  • [ ] version
  • [ ] doc

Is this a regression?

No. Related functionaliy only available with new i18n capabilities of angular 9.

Description

I want to use ng xi18n command to extract messages for i18n tags which are part of a library project which is part of a monrepo setup created by the cli. According to docs at

https://angular.io/cli/xi18n this is supposed to be possible

ng xi18n <project> <project> The name of the project to build. Can be an application or a library.

🔬 Minimal Reproduction

  1. create project: ng new lib-i18n
  2. add localize: ng add @angular/localize
  3. generate library: ng g library my-lib
  4. add i18n attribute in my-lib.component.ts
    <p i18n>
      my-lib works!
    </p>
    
  5. run ng xi18n my-lib: Result will be
    An unhandled exception occurred: Project 'my-lib' does not support the 'extract-i18n' target.
    After adding corresponding extract-i18n target in angular.json, error output as below.

I created a minimal demo project which incorporates the scenario describe above. It is located here: https://github.com/multimike77/lib-i18n-issue

Checkout and run npm install. Then run ng xi18n my-lib and it should produce error as below.

🔥 Exception or Error


An unhandled exception occurred: The "path" argument must be of type string. Received undefined

[error] TypeError [ERR_INVALID_ARG_TYPE]: The "path" argument must be of type string. Received undefined
    at validateString (internal/validators.js:117:11)
    at Object.resolve (path.js:980:7)
    at Object.getCommonConfig (/Users/.../lib-i18n/node_modules/@angular-devkit/build-angular/src/angular-cli-files/models/webpack-configs/common.js:390:24)
    at /Users/.../lib-i18n/node_modules/@angular-devkit/build-angular/src/extract-i18n/index.js:91:27
    at generateWebpackConfig (/Users/.../lib-i18n/node_modules/@angular-devkit/build-angular/src/utils/webpack-browser-config.js:62:22)
    at async Object.generateBrowserWebpackConfigFromContext (/Users/.../lib-i18n/node_modules/@angular-devkit/build-angular/src/utils/webpack-browser-config.js:137:20)
    at async execute (/Users/.../lib-i18n/node_modules/@angular-devkit/build-angular/src/extract-i18n/index.js:73:24)

🌍 Your Environment


Angular CLI: 9.0.4
Node: 12.16.1
OS: darwin x64

Angular: 9.0.4
... animations, cli, common, compiler, compiler-cli, core, forms
... language-service, localize, platform-browser
... platform-browser-dynamic, router
Ivy Workspace: Yes

Package                            Version
------------------------------------------------------------
@angular-devkit/architect          0.900.4
@angular-devkit/build-angular      0.900.4
@angular-devkit/build-ng-packagr   0.900.4
@angular-devkit/build-optimizer    0.900.4
@angular-devkit/build-webpack      0.900.4
@angular-devkit/core               9.0.4
@angular-devkit/schematics         9.0.4
@ngtools/webpack                   9.0.4
@schematics/angular                9.0.4
@schematics/update                 0.900.4
ng-packagr                         9.0.2
rxjs                               6.5.4
typescript                         3.7.5
webpack                            4.41.2

Anything else relevant?

multimike77 avatar Mar 03 '20 09:03 multimike77

Hi @multimike77, thanks for reporting this. The docs seems to be incorrect as i18n extraction is only supported at application level.

alan-agius4 avatar Mar 03 '20 10:03 alan-agius4

Thanks, I thought already that it could be like this. Then I will adjust my expectations for now. Are there any plans to support use cases as this one in a future version?

Overall scenrio would be like that:

  • Library provides its own xlf files containing the translations for text used in the library components
  • Consuming applications can use the translations when creating localized builds

From what I understood from the docs around i18n and ivy in Angular 9, i18n tags are extracted when used in an application. But like this, every application which uses the library will need to provide own translations for the texts used in the library components. This is of course not ideal in regards to reusability.

multimike77 avatar Mar 03 '20 12:03 multimike77

@clydin would know more about this topic.

But like this, every application which uses the library will need to provide own translations for the texts used in the library components. This is of course not ideal in regards to re usability.

I think there are two sides of this, you can also say that the library author shouldn't be responsible for the translations themselves, but only provide a way to localise the library.

Though I do understand that this feature might be useful in some cases.

alan-agius4 avatar Mar 03 '20 13:03 alan-agius4

In the next few weeks (hopefully) I will be working on new translation extraction tooling that understands the new $localize calls. Some of the goals will be to support libraries better. Some ideas:

  • ability to filter the generated translation files to only include translations from specified sets of sources (i.e. not libraries).
  • ability to merge more than one translation file together at the point where we localize an application, so that a library author could provide translation if desired

petebacondarwin avatar Mar 03 '20 13:03 petebacondarwin

I think there are two sides of this, you can also say that the library author shouldn't be responsible for the translations themselves, but only provide a way to localise the library.

Though I do understand that this feature might be useful in some cases. Yes of course, that's also a valid point. Any solution should ideally support either scenario of already shipping with translations or only providing support for translations.

In our case it's like several shared components and libraries which are used in multiple applications created by different teams throughout the company. The texts and translations for the library components should only be done once and be the same across the applications.

In the next few weeks (hopefully) I will be working on new translation extraction tooling that understands the new $localize calls. Some of the goals will be to support libraries better.

This sounds promising @petebacondarwin !

multimike77 avatar Mar 03 '20 14:03 multimike77

@petebacondarwin just to know about timings, are we going to see library extraction tool for angular 10 or before?

meriturva avatar Apr 23 '20 14:04 meriturva

That's my plan! But it will be tight.

petebacondarwin avatar Apr 24 '20 11:04 petebacondarwin

In the next few weeks (hopefully) I will be working on new translation extraction tooling that understands the new $localize calls. Some of the goals will be to support libraries better.

@petebacondarwin: Is there a way to track the progress for these features?

michaelhunziker avatar May 06 '20 11:05 michaelhunziker

@michaelhunziker - I have not made much progress. You can follow the various PRs that are in flight can be seen at https://github.com/angular/angular/pulls?q=is%3Apr+is%3Aopen+label%3A%22comp%3A+i18n%22+

petebacondarwin avatar May 06 '20 15:05 petebacondarwin

@petebacondarwin - is there a way I could use a cmd like localize-translate to do what ng xi18n does? I tried below command, but it still requires -t which is looking for translated files and don't have these files yet. I want to extract i18n attributes in the HTML to messages.xlf. I need to do this in Angular 10.0.3 (localize-extract is not supported). It is okay if just HTML messages get into the messages.xlf file. Please let me know if there is a work around?

node_modules/.bin/localize-translate --root=dist/libs/my-lib --source=bundles/**/* -o projects/libs/my-lib/src/locale/

sistla001 avatar Oct 06 '20 23:10 sistla001

@sistla001 - yes. It is called localize-extract. Try something like

tsc -p tsconfig.app.json
node_modules/.bin/localize-extract -s "out-tsc/**/*.js" -f xlf -o message.xlf

petebacondarwin avatar Oct 07 '20 08:10 petebacondarwin

node_modules/.bin/localize-extract -s "out-tsc/**/*.js" -f xlf -o message.xlf

yeah, but localize-extract is not included with cli 10.0.3, is there an equivalent command that I can use in 10.0.3 library project?

sistla001 avatar Oct 07 '20 13:10 sistla001

It is available in @angular/localize version 10.1.0. It is independent of the CLI version.

petebacondarwin avatar Oct 07 '20 13:10 petebacondarwin

@petebacondarwin what is the right way to extract messages from the library in Angular 11.0.0?

"lib": {
      "projectType": "library",
      ...
      "architect": {
         "extract-i18n": {
          "builder": "@angular-devkit/build-angular:extract-i18n",
          "options": {
            "browserTarget": "lib:build",
            "outFile": "messages.xlf",
            "outputPath": "libs/lib/src/i18n",
            "format": "xlf",
            "ivy": true
          }
        }
      }
}

and then I've tried command:

ng run lib:extract-i18n

Ivy extraction enabled but application is not Ivy enabled. Extraction may fail.
An unhandled exception occurred: The "path" argument must be of type string. Received undefined

kostetskyroma avatar Nov 12 '20 12:11 kostetskyroma

Extracting library messages via CLI is not yet supported. You could use localize-extract as described above to do it manually, after building the library in ivy mode.

petebacondarwin avatar Nov 12 '20 13:11 petebacondarwin

Do you think you could add a library paragraph in Angular documentation (https://angular.io/guide/i18n) ?

I have a workspace with one library and one project. I just spend two hours to finally found that I just needed to apply https://github.com/angular/angular/issues/29536#issuecomment-774861859 : add in package.json > projects > my-lib > architect :

        "extract-i18n": {
          "builder": "@angular-devkit/build-angular:extract-i18n",
          "options": {
            "browserTarget": "angular-i18n:build"
          }
        },

to generate with ng extract-i18n a single messages.xlf file for my app and my library.

bansan85 avatar Aug 16 '21 06:08 bansan85

@bansan85 with your proposed solution on a multi libraries project extraction tool just extracts all translations not only the library one.

@petebacondarwin I could prepare a simple project and open a new issue if needed.

meriturva avatar Aug 17 '21 09:08 meriturva

Just a heads up that we kicked off a community voting process for your feature request. There are 20 days until the voting process ends.

Find more details about Angular's feature request process in our documentation.

angular-robot[bot] avatar Feb 01 '22 18:02 angular-robot[bot]

It's good to see some movement here with the voting process. Despite having localize-extract as a workaround, it would be great to have some permanent and standardized solution included in the cli tooling.

Localize-extract was working fine for me so far, although sometimes seems to miss to extract some keys. When running the main app, which then includes the xlf file generated for the library, the warnings for missing keys do show up on console.

multimike77 avatar Feb 16 '22 15:02 multimike77

Sadly this feature is required only by ten developers, not enough I guess. So we still use and maintain our custom script.

meriturva avatar Feb 16 '22 15:02 meriturva

Sadly this feature is required only by ten developers, not enough I guess. So we still use and maintain our custom script.

then at least 11

robert-brower-impaq avatar Feb 16 '22 20:02 robert-brower-impaq

I am on angular 13, and I spent all the morning trying to figure out why the localize-extract was not extracting the i18n texts from the html template files, it was only extracting $localize from the ts files. Finally found that I had to compile the lib in development, Ivy full compilation mode.

Btw, having this bundled in the cli would help.

jllodra avatar Apr 01 '22 10:04 jllodra

I am on angular 13, and I spent all the morning trying to figure out why the localize-extract was not extracting the i18n texts from the html template files, it was only extracting $localize from the ts files. Finally found that I had to compile the lib in development, Ivy full compilation mode.

Btw, having this bundled in the cli would help.

For anyone else wondering: I had to create another configuration in angular.json > projects > architect > build > configurations like this:

"i18n": {
  "tsConfig": "tsconfig.lib.i18n.json",
  "project": "ng-packagei18n.json"
}

The project was used to specify a different directory (to avoid overriding existing dists), and in the tsConfig the important options are:

"angularCompilerOptions": {
  "ivy": true,
  "compilationMode": "full",
  "skipTemplateCodegen": false
}

Especially the last one, because Angular sets it to true by default for libraries, this was my problem

Xriuk avatar Jun 21 '22 15:06 Xriuk

I am on angular 13, and I spent all the morning trying to figure out why the localize-extract was not extracting the i18n texts from the html template files, it was only extracting $localize from the ts files. Finally found that I had to compile the lib in development, Ivy full compilation mode.

Btw, having this bundled in the cli would help.

For anyone else wondering: I had to create another configuration in angular.json > projects > architect > build > configurations like this:


"i18n": {

  "tsConfig": "tsconfig.lib.i18n.json",

  "project": "ng-packagei18n.json"

}

The project was used to specify a different directory (to avoid overriding existing dists), and in the tsConfig the important options are:


"angularCompilerOptions": {

  "ivy": true,

  "compilationMode": "full",

  "skipTemplateCodegen": false

}

Especially the last one, because Angular sets it to true by default for libraries, this was my problem

What about libraries that are needed to be published to registries? It says, they have to have compilationMode=partial, otherwise I get an error that it can't be published.

sistla001 avatar Jul 23 '22 12:07 sistla001

I am on angular 13, and I spent all the morning trying to figure out why the localize-extract was not extracting the i18n texts from the html template files, it was only extracting $localize from the ts files. Finally found that I had to compile the lib in development, Ivy full compilation mode.

Btw, having this bundled in the cli would help.

For anyone else wondering: I had to create another configuration in angular.json > projects > architect > build > configurations like this:


"i18n": {

  "tsConfig": "tsconfig.lib.i18n.json",

  "project": "ng-packagei18n.json"

}

The project was used to specify a different directory (to avoid overriding existing dists), and in the tsConfig the important options are:


"angularCompilerOptions": {

  "ivy": true,

  "compilationMode": "full",

  "skipTemplateCodegen": false

}

Especially the last one, because Angular sets it to true by default for libraries, this was my problem

What about libraries that are needed to be published to registries? It says, they have to have compilationMode=partial, otherwise I get an error that it can't be published.

You use this configuration only to extract translation strings, if you wanna publish your library you recompile it in partial mode with another configuration

Xriuk avatar Jul 23 '22 13:07 Xriuk

I am on angular 13, and I spent all the morning trying to figure out why the localize-extract was not extracting the i18n texts from the html template files, it was only extracting $localize from the ts files. Finally found that I had to compile the lib in development, Ivy full compilation mode.

Btw, having this bundled in the cli would help.

For anyone else wondering: I had to create another configuration in angular.json > projects > architect > build > configurations like this:


"i18n": {

  "tsConfig": "tsconfig.lib.i18n.json",

  "project": "ng-packagei18n.json"

}

The project was used to specify a different directory (to avoid overriding existing dists), and in the tsConfig the important options are:


"angularCompilerOptions": {

  "ivy": true,

  "compilationMode": "full",

  "skipTemplateCodegen": false

}

Especially the last one, because Angular sets it to true by default for libraries, this was my problem

What about libraries that are needed to be published to registries? It says, they have to have compilationMode=partial, otherwise I get an error that it can't be published.

You use this configuration only to extract translation strings, if you wanna publish your library you recompile it in partial mode with another configuration

Ok, this may work for the libraries we own. But, any ideas on how texts can be extracted from Kendo/3rd party Libraries? here's the command that used to work with Angular 10 and no longer works after upgrading to angular 14.

node_modules/.bin/localize-extract -s node_modules/@progress/**/dist/fesm2015/*.js -f xlf -o src/locale/xlfs/kendo-messages.xlf. Thanks!

~~Update: looks like ng extract-i18n <project> --format xlf --output-path src/locale is extracting all texts across custom libraries, kendo (3rd parties) and also does the merge. This is exactly what I am looking for. With angular 10, I was using localize-extract multiple times, then xlf-merge to merge the messages, and then use @ngx-i18nsupport/tooling to merge into language files.~~

Update: ng-extract-i18n-merge is the library that is letting me extract all texts across custom libraries, kendo (3rd parties), and also does the language merge. Hope this will end up in cli one day. CC; @petebacondarwin

sistla001 avatar Jul 23 '22 13:07 sistla001

Wanted to comment for visibility. I'm working on a project that use a monorepo with multiples apps/projects where we want to make use of incremental builds. To do so, our library needs to import '@angular/localize/init'; to make the compiler happy and not get a missing import error.

We don't seems to have any issue with it so far, but would like to understand more about potential issues about it.

Are there any known best practices for libraries translation as this issue seems blocked for a long time now.

k3v3n avatar Feb 15 '23 12:02 k3v3n

We also use import '@angular/localize/init'; in our library. And we mark strings to be localized with i18n attribute or $localize() function in the library. Then our app will extract all strings, both from the app itself and the library. This has been working well for us for many months now.

PowerKiKi avatar Feb 16 '23 02:02 PowerKiKi

Here is an old discussion about library (APF format) and i18n: https://github.com/angular/angular/issues/38366#issuecomment-672932976

Basically, on my teams, we have more than 100 library projects with translations packed inside plus a schematic that just merge strings from libraries used to xlif file produced by the final app. Just a custom way to make it possible to distribute translations near the library. Another approach is the one chosen by Kendo UI, which just has a big library with all strings from all components plus a script that merge strings on xlif.

What we would like to expect is to have

  1. a way to extract only strings from one library (now we have a custom script that splits the whole extraction to make a single group of strings and packs them to the correct library to distribute)
  2. a way to indicate translations into library APF format (maybe package.json)
  3. a way to read translations from the library and merge them to the final xlif app file

I mean, it is something that we do every day with a custom "build pipeline" but I guess a goal is to propose an official approach to cover this need, mainly for small libraries and not-so-big teams.

My two cents.

meriturva avatar Feb 16 '23 07:02 meriturva

a way to read translations from the library and merge them to the final xlif app file

Pretty sure this is solved already, because it turns out that angular.json property projects.my-project.i18n.locales.my-locale can take a string or an array of strings. If you supply multiples paths to xliff files, those will be "merged" when compiling the localized versions of the bundles.

So basically something like that:

{
    "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
    "projects": {
        // ... other things here...
        "my-project": {
            "i18n": {
                "locales": {
                    "en": [
                        "node_modules/my-library/i18n/messages.en.xlf",
                        "client/i18n/messages.en.xlf"
                    ],
                    "es": [
                        "node_modules/my-library/i18n/messages.es.xlf",
                        "client/i18n/messages.es.xlf"
                    ]
                }
            }
        }
    }
}

PowerKiKi avatar Feb 16 '23 10:02 PowerKiKi