README
dfx-translate
A simple translation package for Angular 4 - 12.
Features
- inline html translations with pipelines
- in-code translation with services
- an easy-to-use json structure
- auto-translation feature via LibreTranslate API integration
Information
- Supported languages for auto-translation
- Development notes
- Deployment notes
- Project website
- created with Angular , used libraries
Setup
Installation
npm install dfx-translate@latest
Language file setup
Language files must be saved in src/assets/i18n/LANGUAGE_CODE.json
; Create the directory if it does not exist.
mkdir -p ./src/assets/i18n
Choose a primary language, lets say you've picked english. Create an en.json
file with following content:
{
"WELCOME": "Welcome",
"WELCOME_SUBTEXT": "stranger."
}
Note: The json structure must always consist of a key and value pair.
Manual translation
Choose an additional language, lets say you've picked german. Create an de.json
file
{
"WELCOME": "Willkomen",
"WELCOME_SUBTEXT": "Fremder."
}
Note: You do not have to translate all strings if you are using the auto-translate feature.
Auto translation
dfx-translate can translate the primary language into a whole new language and will take partially manual translated
languages into account, meaning it will only translate strings which are not occurring in the manual created files
located at src/assets/i18n/LANGUAGE_CODE.json
.
Registration in root (app) module
This has to be done only once in the project. Ideal in app.module.ts
import {DfxTranslateModule} from "dfx-translate";
@NgModule({
declarations: [...],
imports: [
...
DfxTranslateModule.setup({
configuration: {
defaultLanguage: 'de',
useLocalStorage: false
}
})
],
bootstrap: [...]
})
export class AppModule {
}
property | description | default value |
---|---|---|
defaultLanguage | Short code of the primary language (identically to the file name) | en |
useLocalStorage | Saves selected languages as the preference into local storage | true |
Registration in feature module
import {DfxTranslateModule} from "dfx-translate";
@NgModule({
declarations: [...],
imports: [
...
DfxTranslateModule,
],
})
export class FeatureModule {
}
Usage
Switching languages
Language switching is as easy as one function call.
Note: The language code used has to exist as src/assets/i18n/LANGUAGE_CODE.json
import {TranslateService} from "dfx-translate";
@Component({
selector: 'app-example',
templateUrl: ...,
styleUrls: [...],
})
export class ExampleComponent {
constructor(private translator: TranslateService) {
}
setLang(lang: string) {
this.translator.use(lang);
}
}
Pipeline usage
Import DfxTranslateModule
into the module requiring the translation pipe.
import {DfxTranslateModule} from "dfx-translate";
@NgModule({
declarations: [...],
imports: [
...
DfxTranslateModule,
...
],
exports: [...]
})
export class ExampleModule {
}
Now you can use it with tr
in html
<h1>{{'WELCOME' | tr}}</h1>
<span>{{'WELCOME_SUBTEXT' | tr}}</span>
Service usage
Access translations via code with TranslateService
import {TranslateService} from "dfx-translate";
@Component({
selector: 'app-example',
templateUrl: ...,
styleUrls: [...],
})
export class ExampleComponent {
constructor(private translator: TranslateService) {
}
save() {
window.alert(this.translator.translate('WELCOME'));
}
}
Auto deep learning translation
It's possible to translate not manual translated strings via LibreTranslate API. LibreTranslate is an open-source, self-hostable machine-translation service.
dfx-translate can translate the primary language into a whole new language and will take partially manual translated languages into account, meaning it will only translate strings which are not occurring in the manual created files located at src/assets/i18n/LANGUAGE_CODE.json.
Command syntax:
node ./node_modules/dfx-translate/translation/generateTranslation.js {API_URL} {SOURCE_LANGUAGE_CODE} {TARGET_LANGUAGE_CODE}
Note: You never have to auto-translate fully manual translated files
Supported languages
LANGUAGE_CODE | name |
---|---|
en | English |
ar | Arabic |
zh | Chinese |
fr | French |
de | German |
hi | Hindi |
ga | Irish |
it | Italian |
ja | Japanese |
ko | Korean |
pt | Portuguese |
ru | Russian |
es | Spanish |
Note: Keep in mind that at least one of the fully manual translated files has to be in such a language for this feature to work.
Example
- Primary language: en; Fully translated language: de; Partially translated language: es; Not translated
language: fr
Following files should be innode ./node_modules/dfx-translate/translation/generateTranslation.js https://translate.abc.abc/translate en es node ./node_modules/dfx-translate/translation/generateTranslation.js https://translate.abc.abc/translate en fr
src/assets/i18n/
folder.en.json
- the primary languagede.json
- additional language, fully manual translatedes.json
- additional language, partially manual translatedes_auto.json
- additional language, auto-translated missing strings ofes.json
compared to the primary languagefr_auto.json
- additional language, completely auto-translated containing all translations
Simplifying
For simplicity purposes I wrote a little shell script. Put this at the top / root level of the project
#!/usr/bin/env bash
main () {
node ./node_modules/dfx-translate/translation/generateTranslation.js https://translate.abc.abc/translate en de
node ./node_modules/dfx-translate/translation/generateTranslation.js https://translate.abc.abc/translate en fr
node ./node_modules/dfx-translate/translation/generateTranslation.js https://translate.abc.abc/translate en es
node ./node_modules/dfx-translate/translation/generateTranslation.js https://translate.abc.abc/translate en it
node ./node_modules/dfx-translate/translation/generateTranslation.js https://translate.abc.abc/translate en pt
# If you have any prettier library intstalled, execute it here
# prettier --config ./.prettierrc --write ./src/assets/i18n
printf "\nFinished!"
}
time main
Now you only have to run this script.
Development
Everything important in this library is located in projects/dfx-translate
, that's the "real" library. (following
commands still have to be executed at the root level)
Dependency installation
npm install
Starting in development environment
npm run-script watch
Building a production version
npm run-script build
Deployment notes
dfx-translate deployments are managed via .gitlab-ci
All builds are uploaded to releases.datepoll.org/common/dfx-translate
Development builds
Commits to the development branch create a dev build downloadable via this link.
Production builds
Tags create a release build downloadable via this link. Additionally, a versioned zip is uploaded and the package is published to npm.