Perform actual translations on your site
Unlike a lot of i18n tools that use the word "translate" in their name, decyphr-i18nr actually translates the text in your application to one or more languages. So long as you have your i18n and source language in place, deycphr-i18nr can take care of the rest of your process, allowing you to continue implementating your functionality, without needing to put your text through a translator tool. During the development of some web applications I used Google Translate to help me quickly put together translations of my sites, which involved a lot of manual copying and pasting which was tedious, laborious, time consuming and error prone. As a solution for this, I built a server side component to handle the integration with the Google Translate API and decyphr-i18nr to send the text to the API to be translated and from that, generate the translation files for the developer. This has sped up development and reduced the amount of silly mistakes of text been pasted into the wrong files, etc.
Simply specify the JSON, YAML or PHP file you wish to translate and the language that you which to translate and it will generate your translations. decyphr-i18nr knows that it's not perfect so if you need to fix any of the content that it translated, you can simply update the specific item that's incorrect, and decyphr-i18nr will leave existing translations as they are, so you can rest assured that if you did need to fix some text, then decyphr-i18nr won't re-translate any text, or override any of the changes that you've made.
decyphr-i18nr is not a substitute for existing internationalization tools. decyphr-i18nr is intended to work with your internationalization tool to provide the translations that will be injected to the site via the internationalization tool.
For example, if you are using React, you may be using react-intl or react-i18next to implement the overall infrastructure, and separating your site content out into a separate JSON file, then you can use decyphr-i18nr to translate the initial language into as many other langauges as you choose.
decyphr-i18nr requires you to have your one JSON file created for your initial langauage, but it will use this JSON structure to generate new files for any languages that you choose
decyphr-i18nr is not 100% accurate. Translations are provided by Google Translate, and therefore decyphr-i18nr will only be as accurate as Google Translate. With that being said, it is pretty good, but do expect some things to be not quite right.
decyphr-i18nr does not support much at the moment. So far we support JSON files and YAML files of any depth, but are working on being as widely supported as possible.
decyphr-i18nr does now support the translation of PHP files that are commonly used within the PHP ecosystem, with frameworks like Laravel, however once translated, the order of the array is not honoured. This is a known bug.
Take a look at the examples directory to see some of the structures that decyphr-i18nr
can work with.
decyphr-i18nr is currently available on NPM and can be installed globally with:
sudo npm i -g decyphr
Once installed, the decyphr
command will be available.
Or, you can install decyphr-i18nr
as a dependency in your project with:
npm i --save-dev decyphr
And add it to your npm scripts:
"translate:pt": "./node_modules/.bin/decyphr json i18n/translations/en.json -t pt"
This way you can just run translate your projects with an npm command:
npm run translate:pt
decyphr-i18nr
also supports JSON configuration files. Currently decyphr
will look in the directory that the command is being called from.
decyphr-i18nr
currently supports two settings in the configuration file:
translationDir
languages
The directory where your translations are housed. If you have this setting configured, decyphr
will also look in that directory for the input file, and always output that directory.
{
"translationDir": "i18n/translations/"
}
Place this config in the directory that you run the decyphr
command from and you'll only need to specify the name of the file:
decyphr json en.json -t pt
Will retrieve the file from i18n/translations/en.json
and output to i18n/translations/pt.json
.
Similarly:
decyphr json loginpage/en.json -t pt -o loginpage/
Will retrieve the file from i18n/translations/loginpage/en.json
and output to i18n/translations/loginpage/pt.json
This can also be used in the above NPM example:
"translate:pt": "./node_module/.bin/decyphr json en.json -t pt
An array of 2-digit language code strings. If you specify languages
in your settings, you will be able to translate the input file to multiple langauges at once without needing to provide a target language.
{
"translationDir": "i18n/translations/",
"languages": ["pt", "es", "fr", "ga", "it", "zt"]
}
Then when running:
decyphr json en.json
a translation will be created for each language specified in the languages array.
This works in the same way within a Node project:
"translate": "./node_module/.bin/decyphr json en.json
Then you'll only need to run:
npm run translate
In addition to the decyphr help
command, decyphr
currently comes with the following commands.
text
json
yaml
supported_languages
find_language
json
will translate a JSON file that you specify and generate the translated file with the language specified.
This takes one required argument of filename and one required flag of -t or --target_lang with one optional parameter of -o or --output_dir to specify the location of the new translation file.
filename
- the name of the file to translate (can include a path)-t
/--target_lang
- a 2-digit language identifier used to inform what the target language is-o
/--output_dir
- the path to where you want the file to be output. A filename will be generate, so don't include one. If left blank, the file will be placed the same location as the input directory.
USAGE
$ decyphr json [FILE]
OPTIONS
-h, --help show CLI help
-o, --output_dir=output_dir The dir that you want the new file to be placed in
-t, --target_lang=target_lang Two-character code for the target language
EXAMPLES
$ decyphr json en.json -t pt
$ decyphr json en.json --target_lang pt
$ decyphr json en.json -t pt -o translations/
$ decyphr json en.json --target_lang pt --output_dir translations/
Translate the en.json file that's in the translations
folder and output the Portuguese translations to the same folder -
decyphr json translations/en.json -t pt
# outputs - a new file called `pt.json` in the `translations` directory
Or translate the en.json file that's in the translations
folder and output the Portuguese translations to current directory -
decyphr json translations/en.json -t pt -o ./
# outputs - a new file called `pt.json` in the current directory
The input langauge will be determined based on the content being translated, rather than the name of the file or any other flag.
To see examples of what the output looks like then checkout the examples
folder. In all cases the source language used was English, and any non-en.json
files were automatically generated using this command.
yaml
will translate a YAML file that you specify and generate the translated file with the language specified.
This takes one required argument of filename and one required flag of -t or --target_lang with one optional parameter of -o or --output_dir to specify the location of the new translation file.
filename
- the name of the file to translate (can include a path)-t
/--target_lang
- a 2-digit language identifier used to inform what the target language is-o
/--output_dir
- the path to where you want the file to be output. A filename will be generate, so don't include one. If left blank, the file will be placed the same location as the input directory
Translates a YAML file and generates a new file containing the translations
USAGE
$ decyphr yaml [FILE]
OPTIONS
-h, --help show CLI help
-o, --output_dir=output_dir The dir that you want the new file to be placed in
-t, --target_lang=target_lang Two-character code for the target language
EXAMPLES
$ decyphr yaml en.yaml -t pt
$ decyphr yaml en.yaml --target_lang pt
$ decyphr yaml en.yaml -t pt -o translations/
$ decyphr yaml en.yaml --target_lang pt --output_dir translations/
Translate the en.yaml file that's in the translations
folder and output the Portuguese translations to the same folder -
decyphr yaml translations/en.yaml -t pt
# outputs - a new file called `pt.yaml` in the `translations` directory
Or translate the en.yaml file that's in the translations
folder and output the Portuguese translations to current directory -
decyphr yaml translations/en.yaml -t pt -o ./
# outputs - a new file called `pt.yaml` in the current directory
The input langauge will be determined based on the content being translated, rather than the name of the file or any other flag.
To see examples of what the output looks like then checkout the examples
folder. In all cases the source language used was English, and any non-en.yaml
files were automatically generated using this command.
NOTE: There is a known bug in the PHP translator, in that it doesn't honour the order in the output file. All of the keys will remain, and are translated correctly, order is just not the same as the input file.
php
will translate a PHP file that you specify and generate the translated file with the language specified.
This takes one required argument of filename and one required flag of -t or --target_lang with one optional parameter of -o or --output_dir to specify the location of the new translation file.
filename
- the name of the file to translate (can include a path)-t
/--target_lang
- a 2-digit language identifier used to inform what the target language is-o
/--output_dir
- the path to where you want the file to be output. A filename will be generate, so don't include one. If left blank, the file will be placed the same location as the input directory
Translates a PHP file and generates a new file containing the translations
USAGE
$ decyphr php [FILE]
OPTIONS
-h, --help show CLI help
-o, --output_dir=output_dir The dir that you want the new file to be placed in
-t, --target_lang=target_lang Two-character code for the target language
EXAMPLES
$ decyphr php en.php -t pt
$ decyphr php en.php --target_lang pt
$ decyphr php en.php -t pt -o translations/
$ decyphr php en.php --target_lang pt --output_dir translations/
Translate the en.php file that's in the translations
folder and output the Portuguese translations to the same folder -
decyphr php translations/en.php -t pt
# outputs - a new file called `pt.php` in the `translations` directory
Or translate the en.php file that's in the translations
folder and output the Portuguese translations to current directory -
decyphr php translations/en.php -t pt -o ./
# outputs - a new file called `pt.php` in the current directory
The input langauge will be determined based on the content being translated, rather than the name of the file or any other flag.
To see examples of what the output looks like then checkout the examples
folder. In all cases the source language used was English, and any non-en.php
files were automatically generated using this command.
NOTE - Configuration files are not supported with the text translator
text
is a simple command that will translate a given piece of text and translate it to the target language.
This takes one required argument of text and one required flag of -t or --target_lang.
text
- a string of text that you want to translate-t
/--target_lang
- a 2-digit language identifier used to inform what the target language is
USAGE
$ decyphr text [TEXT]
OPTIONS
-h, --help show CLI help
-t, --target_lang=target_lang Two-character code for the target language
EXAMPLES
$ decyphr text hello -t pt
$ decyphr text hello --target_lang pt
$ decyphr text "tudo bem?" --target_lang en
For example, to translate the word hello into Portuguese, then use -
decyphr text hello -t pt
# outputs - "hello" translates to "Olá"
Longer strings of text can also be used -
decyphr text "hello, my name is Aaron" -t pt
# outputs - "hello, my name is Aaron" translates to "Olá, meu nome é Aaron"
The input language is automatically determined, so you don't need to specify the input language, and you can use any language as input -
decyphr text "esta frase é portuguesa e será traduzida para o francês" -t fr
# outputs - "esta frase é portuguesa e será traduzida para o francês" translates to "cette phrase est portugaise et sera traduite en français"
Returns a list of the supported language codes and the names of the languages.
Outputs the list of supported languages
USAGE
$ decyphr supported_languages
EXAMPLE
$ decyphr supported_languages
This command will allow you to search for a language in our list of supported languages based on the language name or the code.
This command has two available flags:
-c
/--code
- a 2-digit language identifier-n
/--name
- the name of the language
If both flags are provided, -c
will override -n
Search for a language based on the code or name
USAGE
$ decyphr find_language
OPTIONS
-c, --code=code Two-character code for the target language
-h, --help show CLI help
-n, --name=name The name of the langauge you want to check
EXAMPLES
$ decyphr find_language -n Portuguese
$ decyphr find_language -c pt
If you search for a language name that can be found easily, it will output the language code and name:
decyphr find_language -n portuguese
# outputs - pt => Portuguese
Same for the code:
decyphr find_language -c pt
# outputs - pt => Portuguese
If an item can't be found it will return an error suggesting to lookup the entire list:
decyphr find_language -c pa
# outputs - Error: Could not find pt. Try tunning 'supported_languages'
And if you code that contains more or less than two characters an error will be thrown:
decyphr find_language -c pt-br
# outputs - Error: Language code: pt-br should only contain 2 characters
I would like decyphr-i18nr to be as widely supported as possible. Not just in Node or PHP environments, however I don't have a whole of experience with working with Internationalization in any frameworks beyond Django and React so any contributions to decyphr-i18nr would be more than welcome. If something is missing that you would like, or if you find any bugs, or anything else then fork the repo, make your changes and issue a pull request and I will review the changes.
The projects page on Github has a list of features that I have planned to work on, so if there's something that you would like to work on, either choose it from there or create a new item to work on.
If you find any issues, please log them as issues in GitHub so that they can be worked on, or if you'd like, fix the code and create a pull request.