Loading Translation Files
@codeandweb/ngx-translate does not come with a loader. The reason for this is to keep the module as small as possible and to make it adaptable to your needs.
However, there’s an official plugin called @codeandweb/http-loader
that implements
a dynamic loader.
Static Translations via import
The easy way to set translation data is using import
and setTranslation()
.
The advantage of this is, that the translations are available immediately when loading the app. The big disadvantage is that this binds all translations into your app. If you have many texts and languages, this might bloat your application and slow down startup time.
Loading translations dynamically
ngx-translate
comes with TranslateHttpLoader
, which loads translation files
using HttpClient
. To use it, you need to install the http-loader
package from
@ngx-translate
:
Here is how you would use the TranslateHttpLoader
to load
translations from "/assets/i18n/[lang].json"
. [lang]
is the lang that you’re using, for english it could be en
.
You can override the paths when creating a new instance of the TranslateHttpLoader
:
In newer versions of Angular, the assets
folder is no longer used. Instead,
translations are stored in the public
folder. For this, you can initialize the
TranslateHttpLoader
like this:
You need to create the TranslateLoader
inside a factory method if you’re using
AoT compilation or
Ionic. However, it’s generally a good practice to use this
approach to initialize the paths, even when AoT compilation is not required.
Standalone Components
This configuration is for standalone components. If you don’t have a app.config.ts
you are
most likely using an NgModules
NgModule
Use this if you are using an app.module.ts
. If this file does not exist, you are most likely using
standalone components.
ngx-translate uses JSON translation files by default when using the TranslateHttpLoader
.
These files have the added benefit of being easily embedded directly into your application
using import
.
The modular design of ngx-translate also makes it easy to switch to other file formats by implementing your own loader or using one of the plugins.
Where to store the Translation Files
In older Angular versions, translation files are typically stored in the /src/assets/i18n
folder.
Starting with Angular 18+, the assets
folder is no longer available, so use the public
folder instead.
Directorypublic
Directoryi18n
- de.json
- en.json
Directorysrc/
- …
We recommend using an i18n
folder within the assets
or public
folder to organize your translation files in one place.
Translation file formats
ngx-translate supports two basic types of translation file structures: flat and nested.
The nested structure enforces a tree hierarchy, which can be more intuitive to display in editors. This structure is less repetitive and may result in smaller file sizes.
Flat Structure
Nested Structure preferred
You should choose one structure and avoid mixing flat and nested structures, as this can lead to confusion and inconsistency in your translation files.
Managing Translations
We highly recommend using BabelEdit to manage your translations. BabelEdit allows you to edit all JSON translation files at once, ensuring consistency across them. Features like PreTranslate also provide a fast preview of your application in other languages.
Why Use Contextual IDs like app.title
?
Using keys like app.title
provides valuable context to both translators and
developers.
For translators, it helps clarify where and how the translation will be
used. Instead of seeing isolated text strings, they can interpret the purpose
of the text based on the structure of the key. For example, app.title
indicates that the string is the title of an application, reducing ambiguity
and improving translation accuracy.
For developers, grouping keys by components or modules (e.g., header.title
,
header.login-link
) makes it easier to manage and maintain translation files. This
structured approach helps organize related translations, simplifying updates
and ensuring consistency across different parts of the application.
Additionally, it allows for different translations of the same word depending on the context. For example, in a table heading where space is limited, you might need to use an abbreviation in one language. IDs keys make this possible without confusion.
Using Translation Text as IDs
Using translation texts as IDs might seem tempting, and there are two main advantages:
-
Fallback: The translation texts will always act as the fallback, so if a translation is missing, the default text is already in place instead of the translation ID.
-
Simplicity: It can be easier to simply wrap strings with translation functions or pipes, as no separate ID management is required.
However, there are several major disadvantages:
-
Fragility: Small changes in the main language will break the connection to all translations. For each change, you’ll need to update the IDs in every translation file.
-
Context-specific translations: Translations cannot differ depending on their use. For example, you might use an abbreviation for a word in a table but the full word in another context.
-
Context for translators: IDs provide valuable context to translators. They understand where a text is used and can choose the most suitable translation for that context.
-
Grouping by component or module: Hierarchical IDs automatically create groups, making it easy to identify which module or component an ID is used in.