Jhlangtool
==========


Jhlangtool is a command line tool built for processing translations in the form of .json files.
It is divided into multiple different utilities, each accessed by a keyword.

It currently supports:

- Generating an excel workbook from translation json files
- Generating json from a corresponding excel workbook

Installation
------------

Install and update using pip_:

.. code-block:: text

    $ pip install jhlangtool

This should add jhlangtool to the system's path variable, allowing you to call it from
the command line.

.. _pip: https://pip.pypa.io/en/stable/quickstart/

Utilities
---------

Generating an excel workbook from translation json files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The *generateExcel* or *toExcel* utility generates an excel workbook listing
the values of json files. It takes the base directory as an argument, which is the directoy in
which the language directories are stored. It generates one spreadsheet for every json file,
and a column for every language (see example spreadsheet below). The first value in
the spreadsheet (first row, first column) will be the json file name when converting back into
json with the *generateJson* or *toJson* utility.




**Note** that currently, it only works
if the json files are direct children from language directories (it will work on
``"./i18n/en/example.json"``, but it will not work on ``"./i18n/en/admin/example.json"``
because *example.json* is not a direct child of *en*). Also, any empty string value in the json file
will be replaced by the empty string identifier ($JHEMPTY by default). The identifier will be converted back
into an empty string when using the generateJson or toJson utility.


.. code-block:: text

    $ jhlangtool generateExcel <path to base directory> [options]


Example directory tree:

.. code-block:: text

    I18n <-- The base directory
      |
      |-+ de
      |   |- audits.json
      |   |- dashboard.json
      |   |- login.json
      |
      |-+ en
      |   |- audits.json
      |   |- dashboard.json
      |   |- login.json
      |
      |-+ es
      |   |- audits.json
      |   |- dashboard.json
      |   |- login.json
      |   |- extra.json <--- The language directories don't necessary have to have the same json files.
      |                      If a file is missing in other directories, the excel file wil treat is as missing keys.
      |
      |-+ fr
      |   |- audits.json
      |   |- dashboard.json
      |   |- login.json

When the command ``$ jhlangtool generateExcel ./i18n`` is used on the example input directory, it
generates an excel file. The audits spreadsheet of that excel file (filled with mock data):

+-------------+----------+---------+---------+---------+
| audits.json |   de     | en      | es      | fr      |
+=============+==========+=========+=========+=========+
|             |          |         |         |         |
+-------------+----------+---------+---------+---------+
| example/key | Hallo    | Hello   | Hola    | Bonjour |
+-------------+----------+---------+---------+---------+
| example/key2| Beispiel | Example | Ejemplo | Exemple |
+-------------+----------+---------+---------+---------+

**Options**
    -f, --filepath The path to the excelfile. Must end with the excel filename and the .xlsx extension. Default is ./output.xlsx.

    -s, --separator The separator for the keys in the excel file. Default is "/".

    -i, --identifier The empty str ( "" <--- ) identifier

    -v, --verbose Enables verbose output (outputs which files are currently being processed and which directory is currently being checked for new files)

    -q, --quiet Disables writing to stdout (disables outputting anything)

    -h, --help Shows a help message


Generating json files from an excel workbook
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The *generateJson* or *toJson* utility is meant to be used with the *generateExcel*
or *toExcel* utility. It takes the path to the excel file as an argument. The excel
file must have the format generated by the *generateExcel* or *toExcel* utility. It
generates a new language directory for every language column in the excel file, with
corresponding json files. It will also convert the empty string identifier into an empty string.

.. code-block:: text

    $ jhlangtool generateJson ./output.xlsx

**Options**
    -o, --output In which directory to generate the language json files. Default is the current working directory.
    Note that the json files will be generated in the selected directory (it does not generate
    a new directory inside the selected one).

    -s, --separator The separator for the keys in the excel file. Default is "/".

    -i, --identifier The identifier for the empty string( "" <--- this).

    -v, --verbose Enables verbose output (outputs which files are currently being processed)

    -q, --quiet Disables writing to stdout (disables outputting anything)

    -h, --help Shows a help message

Version: 0.8.0

Author: Martin Vrbovcan, 2018.



