Proposal for i18n support

Current State

gunk has swagger and operation annotations that produce a swagger file.

// +gunk openapiv2.Swagger{
//         Swagger: "2.0",
//         Info: openapiv2.Info{
//                 Title:       "Accounts API",
//                 Description: "Provides CRUD operations on the accounts resource.",
//                 Version:     "1.0.0",
//         },
//         BasePath: "/v1",
//         Schemes: []openapiv2.SwaggerScheme{
//                 openapiv2.HTTPS,
//         },
//         Consumes: []string{
//                 "application/json",
//         },
...

Annotations are based on openapiv2 proto definitions.

The need

Generate documentations in several languages, from both swagger and markdown files.

• swagger files contain the API definition.
• markdown files contain information about the complete service, like the introduction, the authentication process, errors handling etc.

Proposal

Create a documentation generator plugin that will handle the translation.

The plugin should work with the po format as it is an international standard used by translators.

Two steps will be required:

1/ extract all messages that need to be translated from the input files and compile them into one .pot file.

2/ Read .po files to generate a localised documentation.

Step 2 may not be required as drupal is working with po files. Further investigation may be needed to see how it really works.

Extraction

An extract command will go through the gunk definition looking for messages that need translation:

...
Title: {{ gettext "Account API" }},
Description: {{ gettext "This is account API description" }},
...

The same will be performed on markdown files:

# Openbank API {{ gettext "Introduction" }}
{{ gettext "Welcome to the Openbank API documentation."}}

And will output a messages.pot file:

# SOME DESCRIPTIVE TITLE.
# Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
# This file is distributed under the same license as the PACKAGE package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid   ""
msgstr  "Project-Id-Version: \n"
        "Report-Msgid-Bugs-To: EMAIL\n"
        "POT-Creation-Date: 2019-06-18 14:20+0200\n"
        "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
        "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
        "Language-Team: LANGUAGE <LL@li.org>\n"
        "Language: \n"
        "MIME-Version: 1.0\n"
        "Content-Type: text/plain; charset=CHARSET\n"
        "Content-Transfer-Encoding: 8bit\n"

#: gunk/v1/accounts/accounts.gunk:60
msgid   "Account API"
msgstr  ""

#: gunk/v1/accounts/accounts.gunk:61
msgid   "This is account API description"
msgstr  ""

#: templates/introduction.md:1
msgid   "Introduction"
msgstr  ""

#: templates/introduction.md:2
msgid   "Welcome to the Openbank API documentation."
msgstr  ""

Using tools like poedit, translators will be able to produce localised .po and .mo files.

Localisation

The plugin will be able to consume .mo files along with .gunk and markdown files to generate localised documentation.

The plugin will need to know where to find the translation files and the markdown templates files, we could add required params in the generate section of the .gunkconfig file:

[generate documentation]
locales=po
templates=templates
out=docs

The directory will contain translation files, grouped by language:

po
|--- en
|------ en.po
|------ en.mo
|--- fr
|------ fr.po
|------ fr.mo

gunk generate will go through the translations files to generate documentation:

docs
|--- en
|------ en.swagger.json
|------ en.introduction.md
|--- fr
|------ fr.swagger.json
|------ fr.introduction.md

Each swagger and markdown files will have their content translated:

# fr.swagger.json
...
  "info": {
    "title": "Titre en francais",
    "description": "Description en francais",
    "version": "1.0.0"
  },
...

# Openbank API Introduction
Bienvenue sur la documentation de l'API Openbank.