JaMLin

Java Markup Language Internalisation is command line tool for internalisation of markup files (HTML, XML), that keeps markup clean as it was meant to be.

It's like gettext but without need to make markup dirty with anything special functions or custom attributes. It uses JSON files to store your strings. Send these files to your translators with link to JaMLin Editor app.

What is it good for

For projects that use static HTML or XML that need to be translated and keep untouched otherwise. Sometimes you need to keep HTML pure in project without additional attributes, special tags or other languages involved, but with some internalisation tool.

Quick start

In project root, find jamlin_config.json file - copy it to your destination folder and edit CSS selectors to extract what you need (see Config section for more info).
Find jamlin-jar-with-dependencies.jar inside target directory - this one is latest bundled build. Copy it to your destination folder, next to jamlin_config.json file. It can't run without it.
Run as any other Java program using terminal (java -jar jamlin-jar-with-dependencies.jar) as described in next sections using any of 6 defined modes.

How it works

It works in 2 modes Extract and Replace. They are used to:

EXTRACT strings from original HTML or XML. (eg. index.html)
- using CSS selectors from config file JSON.
- creating new JSON where it extracts strings defined by selectors.
REPLACE strings with localised ones.
- uses created JSON with translations.
- creating new HTML or XML or replacing original files (eg. index-en.html).

How to use it

To run it, you need too things defined:

Config file (required)
Parameters (optional)

Config file

Every time you run JaMLin, it's looking for config file, named jamlin_config.json which defines all data needed for extraction in this structure:

{
	"sources": {
		"directories": [
			{
				"path": "templates/",
				"extensions": [ "html", "xml" ],
				"traverse": false,
				"selectors": {
					"texts": {
						"type": "text",
						"selector": "p, a"
					},
					"params": {
						"type": "attribute",
						"selector": "a[title], img[title]",
						"attrName": "title"
					}
				}
			}
		],
		"files": [
			{
				"path": "test-*.html",
				"selectors": {
					"texts": {
						"type": "text",
						"selector": "p, a"
					},
					"params": {
						"type": "attribute",
						"selector": "a[title], img[title]",
						"attrName": "title"
					}
				}
			}
		]
	},
	"target": {
		"save_history": true,
		"replace_pattern": "*-$lang.*"
	}
}

It defines sources and targets:

In sources, you define what texts you want to use for translation. You can traverse whole directories for file with defined extensions or use only selected files. Within these two tools you define tags, you want to use using CSS selectors. You can define your own names for unlimited number of selectors using 3 types - text, attribute and value.
In target you define replace pattern of file and if existing file can be replaced (TODO).

You will probably need separate config for every project.

After you set it up, you can define parameters - action, source, target and language.

JaMLin by default uses "extract" action to traverse defined items and trying to extract their translations. When run with "replace" action, it tries to get new translations back to its original files.

Parameters

JaMLin receives 4 parameters and works in 6 modes. Examples of using Jamlin looks like this:

java -jar jamlin-jar-with-dependencies.jar --action "extract" --source "jamlin_demo.html" --language "sk"

java -jar jamlin-jar-with-dependencies.jar --action "replace" --source "jamlin_demo-extract.json" --target "jamlin_demo.html" --language "en"

Parameters legend:

action (required) - supports 2 values:
- "extract" (default),
- "replace".
source - source file to read, differs according to action:
- for "extract" action it's HTML file,
- for "replace" action it's JSON file generated by "extract" command.
target - target file is for one action only:
- for "replace" action it's HTML file whose name will be used to create file names for target HTML files.
language (optional) - language (eg. "en", "en_US", "zh_CN_#Hans", ...) works two ways:
- for "extract" action it sets, what language version was used for extract strings,
- for "replace" action sets what language you want to output.
dictionary (optional) - creates project dictionary, true by default:
- for "extract" action it creates project-dictionary.json file that contains all phrases and their translations from project.

According to parameters, every action can have 3 modes:

extract
1. lang specific mode - extract one language only.
  java -jar jamlin-jar-with-dependencies.jar --action "extract" --source "jamlin_demo.html" --language "sk"
2. semiautomatic mode - extract and try to get language from source, if not use "xx".
  java -jar jamlin-jar-with-dependencies.jar --action "extract" --source "jamlin_demo.html"
3. full automatic mode - extract all using config (default). Extract action is default.
  java -jar jamlin-jar-with-dependencies.jar
replace
1. lang specific mode - replace one language only.
  java -jar jamlin-jar-with-dependencies.jar --action "replace" --source "jamlin_demo-extract.json" --target "jamlin_demo.html" --language "en"
2. semiautomatic mode - using selected target replace all languages from translation source and create related output files.
  java -jar jamlin-jar-with-dependencies.jar --action "replace" --source "jamlin_demo-extract.json" --target "jamlin_demo.html"
3. full automatic mode - replace all using config (default).
  java -jar jamlin-jar-with-dependencies.jar --action "replace"

Translation

JaMLin does not translate data by itself. It only extracts strings according to your config. To translate it, you need to fill translations into JSON file using this format:

{
  "translationBlocks": [
    {
      "name": "texts",
      "cssSelector": "p, a",
      "type": "text",
      "translationStrings": [
        {
          "stringOrig": "Menu",
          "selector": "#mobile_menu",
          "translations": [
            {
              "langCode": "en",
              "translation": "Menu EN version"
            },
            {
              "langCode": "sk",
              "translation": "Menu SK version"
            }
          ]
        }
      ]
    }
  ]
}

For that, you can use any editor, that can read JSON files or try JaMLin Editor. Check binaries downloads in Jamlin Editor releases - https://github.com/Wradgio/Jamlin-Editor/releases.

Command line shortcut

If you want to have Jamlin available everywhere without need to write whole "java -jar /whole/path/to/jamlin.jar", you can create shortcut into ~/.profile (or ~/.bash_profile) in your home folder - just add this line in it:

alias jamlin="java -jar /home/batman/apps/jamlin.jar"

It should work on terminal windows opened after you saved that.

Why is it such a mess

It's my first tool in Java and Maven, a one man project. It will take some time to clean it up. Any help is appreciated.

Wradgio / Jamlin