From 4b4226d2e00a7fa944601dd8ed76a870445b1d3e Mon Sep 17 00:00:00 2001 From: Colum Ferry Date: Wed, 16 Apr 2025 18:38:22 +0100 Subject: [PATCH] docs(angular): add guide on i18n for Angular Rspack (#30732) ## Current Behavior There is currently no documetation on how to configure i18n for Angular Rspack applications ## Expected Behavior Add documetation giving details on how to configure i18n for Angular Rspack applications --- docs/generated/manifests/menus.json | 32 +++++++ docs/generated/manifests/nx.json | 44 ++++++++++ docs/generated/manifests/tags.json | 18 ++++ docs/map.json | 6 ++ .../angular-rspack/internationalization.md | 88 +++++++++++++++++++ .../guides/angular-rspack/introduction.md | 1 - docs/shared/reference/sitemap.md | 1 + 7 files changed, 189 insertions(+), 1 deletion(-) create mode 100644 docs/shared/guides/angular-rspack/internationalization.md diff --git a/docs/generated/manifests/menus.json b/docs/generated/manifests/menus.json index 2d77e74c45..f67f4b9840 100644 --- a/docs/generated/manifests/menus.json +++ b/docs/generated/manifests/menus.json @@ -1565,6 +1565,14 @@ "isExternal": false, "children": [], "disableCollapsible": false + }, + { + "name": "Internationalization (i18n)", + "path": "/recipes/angular/rspack/internationalization", + "id": "internationalization", + "isExternal": false, + "children": [], + "disableCollapsible": false } ], "disableCollapsible": false @@ -3059,6 +3067,14 @@ "isExternal": false, "children": [], "disableCollapsible": false + }, + { + "name": "Internationalization (i18n)", + "path": "/recipes/angular/rspack/internationalization", + "id": "internationalization", + "isExternal": false, + "children": [], + "disableCollapsible": false } ], "disableCollapsible": false @@ -3160,6 +3176,14 @@ "isExternal": false, "children": [], "disableCollapsible": false + }, + { + "name": "Internationalization (i18n)", + "path": "/recipes/angular/rspack/internationalization", + "id": "internationalization", + "isExternal": false, + "children": [], + "disableCollapsible": false } ], "disableCollapsible": false @@ -3188,6 +3212,14 @@ "children": [], "disableCollapsible": false }, + { + "name": "Internationalization (i18n)", + "path": "/recipes/angular/rspack/internationalization", + "id": "internationalization", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, { "name": "Migration", "path": "/recipes/angular/migration", diff --git a/docs/generated/manifests/nx.json b/docs/generated/manifests/nx.json index 2be66861cd..83d99bc504 100644 --- a/docs/generated/manifests/nx.json +++ b/docs/generated/manifests/nx.json @@ -2143,6 +2143,17 @@ "isExternal": false, "path": "/recipes/angular/rspack/handling-configurations", "tags": ["handling-configurations", "configurations"] + }, + { + "id": "internationalization", + "name": "Internationalization (i18n)", + "description": "", + "mediaImage": "", + "file": "shared/guides/angular-rspack/internationalization", + "itemList": [], + "isExternal": false, + "path": "/recipes/angular/rspack/internationalization", + "tags": ["internationalization", "i18n"] } ], "isExternal": false, @@ -4191,6 +4202,17 @@ "isExternal": false, "path": "/recipes/angular/rspack/handling-configurations", "tags": ["handling-configurations", "configurations"] + }, + { + "id": "internationalization", + "name": "Internationalization (i18n)", + "description": "", + "mediaImage": "", + "file": "shared/guides/angular-rspack/internationalization", + "itemList": [], + "isExternal": false, + "path": "/recipes/angular/rspack/internationalization", + "tags": ["internationalization", "i18n"] } ], "isExternal": false, @@ -4330,6 +4352,17 @@ "isExternal": false, "path": "/recipes/angular/rspack/handling-configurations", "tags": ["handling-configurations", "configurations"] + }, + { + "id": "internationalization", + "name": "Internationalization (i18n)", + "description": "", + "mediaImage": "", + "file": "shared/guides/angular-rspack/internationalization", + "itemList": [], + "isExternal": false, + "path": "/recipes/angular/rspack/internationalization", + "tags": ["internationalization", "i18n"] } ], "isExternal": false, @@ -4369,6 +4402,17 @@ "path": "/recipes/angular/rspack/handling-configurations", "tags": ["handling-configurations", "configurations"] }, + "/recipes/angular/rspack/internationalization": { + "id": "internationalization", + "name": "Internationalization (i18n)", + "description": "", + "mediaImage": "", + "file": "shared/guides/angular-rspack/internationalization", + "itemList": [], + "isExternal": false, + "path": "/recipes/angular/rspack/internationalization", + "tags": ["internationalization", "i18n"] + }, "/recipes/angular/migration": { "id": "migration", "name": "Migration", diff --git a/docs/generated/manifests/tags.json b/docs/generated/manifests/tags.json index 4d91cb28bd..6416af03a6 100644 --- a/docs/generated/manifests/tags.json +++ b/docs/generated/manifests/tags.json @@ -1123,6 +1123,24 @@ "path": "/recipes/angular/rspack/handling-configurations" } ], + "internationalization": [ + { + "description": "", + "file": "shared/guides/angular-rspack/internationalization", + "id": "internationalization", + "name": "Internationalization (i18n)", + "path": "/recipes/angular/rspack/internationalization" + } + ], + "i18n": [ + { + "description": "", + "file": "shared/guides/angular-rspack/internationalization", + "id": "internationalization", + "name": "Internationalization (i18n)", + "path": "/recipes/angular/rspack/internationalization" + } + ], "deployment": [ { "description": "", diff --git a/docs/map.json b/docs/map.json index c22a378cfb..4ad41ca9fe 100644 --- a/docs/map.json +++ b/docs/map.json @@ -737,6 +737,12 @@ "id": "handling-configurations", "tags": ["handling-configurations", "configurations"], "file": "shared/guides/angular-rspack/handling-configurations" + }, + { + "name": "Internationalization (i18n)", + "id": "internationalization", + "tags": ["internationalization", "i18n"], + "file": "shared/guides/angular-rspack/internationalization" } ] }, diff --git a/docs/shared/guides/angular-rspack/internationalization.md b/docs/shared/guides/angular-rspack/internationalization.md new file mode 100644 index 0000000000..df05981ea3 --- /dev/null +++ b/docs/shared/guides/angular-rspack/internationalization.md @@ -0,0 +1,88 @@ +--- +title: 'Build-time Internationalization (i18n) with Angular Rspack' +description: "Guide on how to use Angular's build-time i18n with Angular Rspack" +--- + +# Build-time Internationalization (i18n) with Angular Rspack + +Angular Rspack supports Angular's [build-time i18n](https://angular.dev/guide/i18n) out of the box. This guide will walk you through how to use it. +You can follow the steps completely, just make sure to place any changes to `angular.json` in your project's `project.json` file. Some of these changes may also need to be made to the `rspack.config` file. +The steps below indicate where to make these changes. + +The process of building an Angular Rspack application with i18n is similar to building an Angular application with i18n and reuses most of the same steps and configuration. + +## Prerequisites + +- `@angular/localize` must be installed in your project. +- You must have an `i18n` configuration in your `project.json` file. + +It is assumed you have an `i18n` property in your `project.json` file that looks like this: + +```json {% highlightLines=["3-10"] %} +{ + "name": "my-app", + "i18n": { + "sourceLocale": "en-GB", + "locales": { + "fr": { + "translation": "src/locale/messages.fr.xlf" + } + } + }, + "targets": { + "extract-i18n": {} + } +} +``` + +{% callout type="note" title="Extracting i18n messages" %} +The `extract-i18n` target found in Angular projects will still be used to extract the i18n messages into XLIFF (or chosen format) files. +You simply need to run `nx extract-i18n my-app` to extract the messages. +{% /callout %} + +## Step 1: Configure the Rspack Configuration + +To enable i18n, you need to add the following configuration to your `rspack.config` file: + +```js {% highlightLines=[7,15] %} +export default createConfig( + { + options: { + root: __dirname, + polyfills: [ + 'zone.js', + '@angular/localize/init', + ], + ..., + }, + }, + { + production: { + options: { + localize: true, + }, + }, + } +); +``` + +## Step 2: Run the build + +After configuring the Rspack configuration, you can run the build with the following command: + +```bash +npx nx build my-app +``` + +It will output bundles in the `dist` directory with the following structure: + +```text +dist +├── browser +│ ├── [localeCode] +│ │ ├── main.js +│ │ ├── main.js.map +│ │ ├── index.html +│ │ ├── styles.css +│ │ ├── ... +``` diff --git a/docs/shared/guides/angular-rspack/introduction.md b/docs/shared/guides/angular-rspack/introduction.md index 238cd9e729..1ee145cf62 100644 --- a/docs/shared/guides/angular-rspack/introduction.md +++ b/docs/shared/guides/angular-rspack/introduction.md @@ -42,7 +42,6 @@ Please not that Angular Rspack support is still experimental and is not yet cons The following are known limitations and missing features of Angular Rspack: - Static Site Generation (SSG) is not supported. -- Angular's built-in support for Internationalization (i18n) is not supported. - Server Routing is not supported - still experimental in Angular currently. - App Engine APIs are not supported - still experimental in Angular currently. - Optimization is not currently 1:1 with Angular's optimization - however, there are still great optimizations that are made. diff --git a/docs/shared/reference/sitemap.md b/docs/shared/reference/sitemap.md index 1aac3aed53..2067d77b58 100644 --- a/docs/shared/reference/sitemap.md +++ b/docs/shared/reference/sitemap.md @@ -115,6 +115,7 @@ - [Introduction](/recipes/angular/rspack/introduction) - [Migrate from Angular Webpack](/recipes/angular/rspack/migrate-from-webpack) - [Handling Configurations](/recipes/angular/rspack/handling-configurations) + - [Internationalization (i18n)](/recipes/angular/rspack/internationalization) - [Migration](/recipes/angular/migration) - [Migrating from Angular CLI](/recipes/angular/migration/angular) - [Migrating From Multiple Angular CLI Repos](/recipes/angular/migration/angular-multiple)