Internationalization for documentation

[nohorbee]

By adding a locales root level property, and a keyword to reference text bundles, RAML 1.0 can provide support for localization of documentation.

A resource bundle is a YAML file, which contains a mapping, where each key is the name of a text resource, and each value is the value for that text resource string in a given locale.

#%RAML 0.8
title: !bundle title
locales:
  en_US: !include docs/en_US.bundle.yaml
  es: !include docs/es.bundle.yaml
/users:
  description: !bundle users.description

Where docs/en_US.bundle.yaml contains

title: My Sample API
users.description: The users resource provides access to all users in the system

Where docs/en_US.bundle.yaml contains

title: Mi API de ejemplo
users.description: El recurso users provee acceso a todos los usuarios en el sistema

RAML processors must pick the resource bundle which best matches the consumers locale.

[tgullotta]

Do we need to list the supported locales in the raml doc or can we just identify the root directory of the locales? The locale sub-folders should be named using the standard locale names. That way when someone creates another translation they don’t have to change he raml file itself, just add a new sub-folder.

[blakeembrey]

@tgullotta I think we should always be explicit. Otherwise web tools won't know where or what to load ahead of time.

[usarid]

I guess the question is: do we treat locales like an enum, where the
options are limited, or do we treat them as an unspecified list and the
client must have some sidechannel to know what locales are supported, or
maybe even try one and then default back to something else?

On Wed, Sep 17, 2014 at 11:21 AM, Blake Embrey notifications@github.com
wrote:

@tgullotta https://github.com/tgullotta We should always be explicit.
Otherwise web tools won't know where or what to load.

—
Reply to this email directly or view it on GitHub
#104 (comment).

[blakeembrey]

Do locales cascade when not specified? Google+ has interesting behaviour down to the region for a comparison. E.g. en-GB uses the word "bin", while en-US uses the word "trash".

[svacas]

are there any restrictions regarding where the !bundle tag can be used?
can be used on the key side?
can be used for any value?

[dmartinezg]

@svacas I would alter the wording to say that a !bundle tag should only be used in a scalar context on the value side.

[svacas]

@dmartinezg I think the usage should be restricted even more to documentation related values, otherwise it could be easily abused. You could end up with resources that have different sets of methods depending on the locale or parameters required for some languages and optional for others.

e.g:
type: !bundle flextype
required: !bundle query_param_required

[mjk-at-sag]

1. Is there a way to explicitly access a bundled language? This would let me extract what I want from the bundle.
2. Is there, say localeExtension as an analog to mediaTypeExtension to allow overrides in the URL? I think I can laboriously roll this by hand for just about everything except the title and the top-level documentation, but it would be desirable to have it automated and complete. E.g.

#%RAML NOT_VALID
version: v1
baseUri: http://github.com/{version}{localeExtension}
title: {locale}.title
documentation
  - title {locale}.chapter1title
    !bundle {locale}.chapter1
localeExtension:
  default: en_UK
  required: false
  pattern: ^(?:-)([a-zA-Z]{2})([-_]([a-zA-Z]{2}))?$
  magic: locale is normalized string aa_AA of matching patterns
/users{localeExtension}{mediaTypeExtension}

[johndemic]

Apologies if this is implied by the above, but it would also be desirable to localize query parameters, values, etc.

[sichvoge]

RAML 1.0 will not support an OOTB standard to define internationalization in this version. Nevertheless, it is not out of question to add support in any later version.

[sichvoge]

Right now you can achieve that using overlays.