A simple utility to translate static HTML files.
Supports JSON and YAML dictionaries.
For global installation, needed for CLI uage, run
$ npm install -g static-i18nNote that you can also use this as a Grunt plugin or a gulp plugin.
A simple example should be easy to understand.
With the following files:
www/index.html:
<html>
<head>
<script src="js/app.js"></script>
</head>
<body>
<h1 data-t="my.key"></h1>
<p data-t>other.key</p>
<input type="submit" data-attr-t value-t="other.ok">
</body>
</html>locales/en.json
{
"my": {
"key": "Hey"
},
"other": {
"key": "man",
"ok": "confirm"
}
}locales/fr.json
{
"my": {
"key": "Salut"
},
"other": {
"key": "mec",
"ok": "confirmer"
}
}The following command
$ static-i18n -l en -i en -i fr wwwwill generate:
i18n/index.html
<html>
<head>
<script src="js/app.js"></script>
</head>
<body>
<h1>Hey</h1>
<p>man</p>
<input type="submit" value="confirm">
</body>
</html>i18n/fr/index.html
<html>
<head>
<script src="../js/app.js"></script>
</head>
<body>
<h1>Salut</h1>
<p>mec</p>
<input type="submit" value="confirmer">
</body>
</html>You can optionally specify that interpolation should be applied to the custom attributes on an element. This will translate only the parts of an element wrapped in curly braces {{ }} and leave the rest alone.
With the following files:
www/index.html:
<html>
<head>
<link rel="canonical" data-attr-t data-attr-t-interpolate href-t="{{links.baseAbsolute}}filename.{{links.extension}}" />
</head>
</html>locales/en.json
{
"links": {
"baseAbsolute": "http://www.example.com/",
"extension": "html"
}
}locales/ja.json
{
"links": {
"baseAbsolute": "http://www.example.com/ja/",
"extension": "htm"
}
}The following command
$ static-i18n --locale en --locales en --locales ja wwwWill generate:
i18n/index.html
<html>
<head>
<link rel="canonical" href="http://www.example.com/filename.html" />
</head>
</html>i18n/ja/index.html
<html>
<head>
<link rel="canonical" href="http://www.example.com/ja/filename.htm" />
</head>
</html>This tool has several configuration options to adapt to most common use cases.
When using the CLI, these options can be passed by using the kebab-case version of the key. For example. attrSelector can be passed with
static-i18n --attr-selector my-attr-t ...
-
selector(default:[data-t]): The selector to look for elements to translate. If it is an attribute, the attribute content is used as the key when non empty, otherwise the text of the element is used. -
attrSelector(default:[data-attr-t]): The selector to look for elements -
attrInterpolateSelector(default:[data-attr-t-interpolate]): The selector that should be applied to elements to indicate that interpolation should be performed for the custom attributes on that element -
xml(default:false): Iftrue, enables XML mode for https://github.com/fb55/htmlparser2 which avoids breaking self-closing tags -
attrSuffix(default:-t): Suffix for attr to translate.value-twill be translated and mapped tovalue. -
attrInterpolateSuffix(default:-t-interpolate): Suffix for attr to interpolate the translations. -
useAttr(default:true): Iffalse, the element text is always used as the key, even if the attribute value is not empty. -
nsSeparator(default::): The namespace separator. Useful if keys contain colons. Change it to something else to prevent cutting off the namespace. -
replace(default:false): Iftrue, the element is replaced by the translation. Useful to use something like<t>my.key</t>to translate. -
locales(default:['en'], CLI alias:-i): the list of locales to be generated. All locales need to have an existing resource file. -
fixPaths(default:true): Whentrue, thescript[src]andlink[href]relative paths are fixed to fit the new subdirectory structure. (See example above.) -
locale(default:en, CLI alias:-l): The default locale. -
exclude(default:[]): Files to exclude. Can contain regex (uses normal test) or string (uses startsWith). -
fileFormat(default:json): The file format for the translations. Supportsjson, andymloryamlwhich will be treated as YAML files. The file extension must match this format. -
encoding(default:utf8): The encoding to read files (only works with yaml for now) -
files(default:**/*.html): The files to translate, relative to the base directory. -
baseDir(default:process.cwd(), CLI alias:-d): The base directory to look for translations. Not useful for CLI usage as it is overriden by the directory argument. -
translateConditionalComments(default:false): Translate the content of conditional comments (see #1). This is still experimental, and could fail on edge cases. Open an issue if needed. -
allowHtml(default:false): Allow the usage of HTML in translation -
removeAttr(default:true): Whentrue, removes the attribute used to translate (e.g.data-twill be removed) -
outputDir(default:i18n, CLI alias:-o): The directory to output generated files -
outputDefault(default:__file__): The name for the default locale output files, relative tooutputDir.__file__will be replaced by the current file name -
outputOther(default:__lng__/__file__): The name for the other locales output files, relative tooutputDir.__lng__will be replaced by the current locale -
localesPath(default:locales): The directory of the translations, where each file should be namedLOCALE_NAME.json -
outputOverride: Override outputDefault or outputOther for special cases (default: {}) eg:{ "en": { "index.html": "foo.html" }, "ja": { "index.html": "ja_index.html" } }
-
i18n: Object passed directly toi18next.init. This allows you to override pretty much anything. Read i18next doc for more info.
When using the CLI, outputOverride and i18n options are parsed as JSON.