dgeni [idea] Embed a translation tool

This is an idea, it is not a solution.

After analyzing the markdown doc files, would it be possible to create one or several json files (or other format)? These files contain the data to start building the documentation. These files could then be duplicated to translate the content. Finally dgeni could use these translated files to build the translated documentation.

@petebacondarwin and @PascalPrecht, what do you think? Knowing that this is an idea and it can be other simpler solutions.

Apr 01 '14 06:04 forresst

What kind of data would be in these files? One item per sentence or per doc or per doc property or what?

Apr 01 '14 06:04 petebacondarwin

I do not know what is the best solution. Maybe the same tree as the generated documentation would be easier to find.

For example, angular, for input.js file, you could have:

First step : data extraction

source	target
input.js	./translate-original/partials/api/ng/input/index.json
	./translate-original/partials/api/ng/input/input[checkbox].json
	./translate-original/partials/api/ng/input/input[email].json
	./translate-original/partials/api/ng/input/input[number].json
	./translate-original/partials/api/ng/input/input[radio].json
	./translate-original/partials/api/ng/input/input[text].json
	./translate-original/partials/api/ng/input/input[url].json

And input[number].json content might look like this (This is an example, the content may be different of course, this is just for demonstration. It is obviously necessary to keep the same attributes as those used in dgeni.) :

{ 
  "ngdoc": "input",
  "name": "input[number]",
  "description" : "Text input with number validation and transformation. Sets the `number` validation error if not a valid number.",
  "param": [
       { "name": "ngModel", "type": "string", "optional": "false", "description": "Assignable angular expression to data-bind to." },
       { "name": "name", "type": "string", "optional": "true", "description": "Property name of the form under which the control is published." },
       ......
       { "name": "ngChange", "type": "string", "optional": "true", "description": "Angular expression to be executed when input changes due to user interaction with the input element." }
  ],
  "example": "<example name="number-input-directive">
        <file name="index.html">
         ............
        </file>
      </example>"
}

Second step : Duplicate files (French for example) and translate

This step is done manually by the user.

source	target
./translate-original/partials/api/ng/input/index.json	./fr_FR/partials/api/ng/input/index.json
./translate-original/partials/api/ng/input/input[checkbox].json	./fr_FR/partials/api/ng/input/input[checkbox].json
./translate-original/partials/api/ng/input/input[email].json	./fr_FR/partials/api/ng/input/input[email].json
./translate-original/partials/api/ng/input/input[number].json	./fr_FR/partials/api/ng/input/input[number].json
./translate-original/partials/api/ng/input/input[radio].json	./fr_FR/partials/api/ng/input/input[radio].json
./translate-original/partials/api/ng/input/input[text].json	./fr_FR/partials/api/ng/input/input[text].json
./translate-original/partials/api/ng/input/input[url].json	./fr_FR/partials/api/ng/input/input[url].json

Translation input[number].json file :

{ 
  "ngdoc": "input",
  "name": "input[number]",
  "description" : "Input de type Text avec validation et transformation du nombre. Définit l'erreur de validation `number` si le nombre n'est pas valide",
  "param": [
       { "name": "ngModel", "type": "string", "optional": "false", "description": "Expression d'angular assignable à la donnée liée." },
       { "name": "name", "type": "string", "optional": "true", "description": "Nom de la propriété du formulaire sous laquelle le contrôle est publié." },
       ......
       { "name": "ngChange", "type": "string", "optional": "true", "description": "Expression d'Angular devant être exécutée lorsque l'input change à cause de l'interaction de l'utilisateur avec l'élément input." }
  ],
  "example": "<example name="number-input-directive">
        <file name="index.html">
         ............
        </file>
      </example>"
}

Third step : dgeni generate translated docs

By adding additional information in the configuration file (path json files translated), dgeni generates translated docs.

source	target
./fr_FR/partials/api/ng/input/index.json	./build/docs/fr_FR/partials/api/ng/input/index.html
./fr_FR/partials/api/ng/input/input[checkbox].json	./build/docs/fr_FR/partials/api/ng/input/input[checkbox].html
./fr_FR/partials/api/ng/input/input[email].json	./build/docs/fr_FR/partials/api/ng/input/input[email].html
./fr_FR/partials/api/ng/input/input[number].json	./build/docs/fr_FR/partials/api/ng/input/input[number].html
./fr_FR/partials/api/ng/input/input[radio].json	./build/docs/fr_FR/partials/api/ng/input/input[radio].html
./fr_FR/partials/api/ng/input/input[text].json	./build/docs/fr_FR/partials/api/ng/input/input[text].html
./fr_FR/partials/api/ng/input/input[url].json	./build/docs/fr_FR/partials/api/ng/input/input[url].html

Apr 01 '14 08:04 forresst

@petebacondarwin : I still accurate once, it's an idea, I do not know enough about the core of dgeni to give an example that matches the attributes dgeni.

Apr 01 '14 08:04 forresst

Translation support is a great idea. Let's knock around some ideas together. On 1 Apr 2014 09:12, "Stéphane Reynaud" [email protected] wrote:

@petebacondarwin https://github.com/petebacondarwin : I still accurate once, it's an idea, I do not know enough about the core of dgeni to give an example that matches the attributes dgeni.

Reply to this email directly or view it on GitHubhttps://github.com/angular/dgeni/issues/77#issuecomment-39180414 .

Apr 01 '14 08:04 petebacondarwin

@petebacondarwin : I'm glad you like it the idea. I remain available to help you. In addition, I am currently translating all documentation angular in French, this would allow you to quickly test this feature.

Apr 01 '14 08:04 forresst

We would need to have a way to help keep the translations in synch with the originals. Think about the process. Someone commits a change to the source files, we run dgeni to regenerate the docs. Now the translations are out of synch. How do we inform people about this? It would be good if as much of the process was automated as possible.

Apr 01 '14 09:04 petebacondarwin

Very good point. I think the biggest challenge is here. For now I do not have a good solution. I'll do some research on this.

Should be able to tag the version of the original documentation and the translated version (git commit sha ? version of the product: for example for Angular, the angular version: 1.2.15)

Another idea?

Apr 01 '14 09:04 forresst

I also think that i18n support in general is a very good thing. Translating developer guides to different languages is fortunately not really a big problem, because these documentations are available in markdown files. We could handle that part similar to how I solved this in angular-translate (https://github.com/angular-translate/angular-translate/tree/master/docs/content/guide).

However, the API part is not that easy. Because you won't document your source code in different languages (which is why the API docs of angular-translate are only available in english). Taking a look at the process @forresst described, I wonder when and where in the process would somebody add translations for a different language. Despite from the fact that translations are getting out of sync, even when dgeni generates the json files for different languages, where do the translations for different languages come from? Can we automate that at all?

And yea. No matter what solution comes up. What we always can do, is to provide APIs to let developers write at least their developer guide in different languages and generate docs from that.

Apr 01 '14 13:04 0x-r4bbit

I definitely like @forresst's idea even though I usually consider i18n to be more cross cutting. Maybe dgeni isn't the one generating the JSON files shouldn't these files come from whoever wants to translate API documentation?

Some pseudo code to help visualize Let's say that our API documentation is English and I want to generate French documentation.

So dgeni would:

generate the English JSON for each doc
look in a certain directory with all the other JSON translation files (French included)
loop through each translation file
- obtain translation by overriding doc with the current JSON (if we don't have a property default to English ex. @example)
- generate doc with current translation file

I've not yet delved into the dgeni core either so my example doesn't really reflect the process. Maybe this would be somewhere around extra-docs-added?

Apr 14 '14 12:04 Nate-Wilkins