Internationalized documentation


#1

Is it possible to provide descriptions, titles and user documentation in different languages/cultures in a RAML file? Can current tools handle that when generating documentation from the RAML file?


#2

Hi @uchoa,

Do you mean conversion between languages (e.g. generate a german, french, spanish, uk, and north american version of my docs from one source file), support for you to document your API in a language of your choosing, or support for multiple different descriptions/titles/docs, one per language?


#3

Thank you @comptly.

I mean generating different versions of my docs in different languages. And I supposed it might imply in needing to provide different descriptions/titles/docs, one per language.


#4

No support right now AFAIK, in either MuleSoft’s tools or the community ones. You should be able to write the docs in whichever language you choose, but multiple versions of the docs in one description isn’t possible. Would be interesting to hear this talked through more broadly, maybe in the issues over on the spec Github page, or on these forums.


#5

Should I open an issue on this subject on GitHub?

I see this as a key feature for our use case. We decided to use RAML to describe our APIs. Today they are consumed by Portuguese speaking developers in Brazil and Spanish speaking developers in other countries in Latin America. Very soon, some English speaking developers will need access to this documentation. We would like a lot to provide the documentation on those choices of languages.


#6

I’m not actively working on RAML 1.0, but I know that effort is about to pick up steam, and they will be using GitHub issues for it – so I’d say yea, open an issue to start the discussion.


#7

Hi @uchoa we will address this on RAML 1.0, do you want to take a look at the proposal and make a comment?

https://github.com/raml-org/raml-spec/issues/104