Add a localization REST resource to expose translation messages

Development
#1

Hi devs,

In the context of https://jira.xwiki.org/browse/XWIKI-18491 we’d like to introduce a REST endpoint to resolve translation keys.

The main goal is to allow JavaScript code to use localized messages without having to rely on Velocity code. The JavaScript module that needs to use some translation keys would fetch them using an URL like this:

/xwiki/rest/wikis/{wikiName}/localization/translations?locale=en&prefix=livedata.&key=one&key=two&...

This is endpoint should be called with the GET method, and the following parameters:

  • locale: Optional, defined the locale of the request translation values, otherwise the local of the context will be used.
  • prefix: Optional, a common prefix used for all the provided keys
  • key: (one or many), once for each requested translation key

The response is an object, where the keys as the requested translation keys and the values the raw translation values (i.e., where the parameters are not resolved), for instance:

{
  "this.is.key1": "raw translation {0} 1",
  "key2": "translation 2"
}

This means the client side will be responsible for applying (interpolating) translation parameters.

Letting client side resolving the raw translations values has several advantages:

  • Responses can be cached
  • Translations keys can be pre-fetched before knowning the values of the translations parameters
  • When values change client side, the translations can be updated without having to call the server

WDYT?

#2

+1

Thanks,
Marius

#3

Additional technical detail, the code will be placed in a new xwiki-platform-localization-rest module.

#4

Sounds good to me.

Goes in the direction of being able to have a 100% REST-based architecture one day

#5

+1

#6

+1

raw translation values (i.e., where the parameters are not resolved)

just for info, the idea is to improve this later to be able to pass parameters to the REST API, or to have them resolved on JS side, in which case, is there a plan for having a common API for that?

#7

The two use cases are not exclusive and resolving the parameters server side could be useful.
Regarding a client side localization API, @cdesableau is working on the integration of vue-i18n and iirc @mflorea has some existing code in CKEditor which could be externalized too.

#8

What is indeed missing from the proposal here and which is in the jira issue description is indeed that:

This means the client side will be responsible for applying (interpolating) translation parameters.

#9

This (making a separate HTTP request for each translation to resolve its parameters) is not practical for the front-end so I don’t think we’ll need it.

Yes, we plan to have some JavaScript module to handle this, but it’s outside the scope of this proposal.

#10

The implementation of that javascript tool is, but it’s an important input to explain why the raw value is sent by the API.

#11

The intente of the paragraph quoted below was to explain that. Let me know if you think it’s not exhaustive.

#12

I read too fast the proposal indeed after @surli asking why the raw values were sent.