On Mon, Oct 26, 2009 at 18:59, Thomas Mortagne <thomas.mortagne@xwiki.com> wrote:

Hi devs,

We need to support some way internationalization of everything in the rendering that appear in the UI, for now it's mainly related to macros.

What I propose is to introduce the rule that any displayable String returned by the API (MacroDescriptor#getName, ParameterDescriptor#getDescription, etc.) could be a l10n key. Then the API user call the l10n component to get the final String.

pros: - no need to touch the current API - it avoid having complex API to support l10n specifics and makes pretty much everything depends on l10n component. It's easier for macro author to write a quick macro with some description without having to create l10n resource and call the l10n component just for english for example. - the displayer can control how to get actual translations the way it wants - we need something like that for wiki macros anyway: XWiki does not support translations of objects yet (and for long I guess since the issue is at database level) and it would be a pain to have to copy the content of the macro by language since most of the time the script of the macro would not be related to the language

cons: - it's more work for the API user to filter the String with the l10n component to get the actual final String

One detail I'm not sure of is if we introduce some syntax to explicitly indicate it's a l10n key or if we just always give the String to the l10n component which will return it as it is if it can't find any matching key.

Having an explicit way to indicate a String is a key would be better to track l10n keys bugs but introduce a syntax is always more complex (what chars to choose, how to escape, etc...).

A good candidate found by Vincent would be to reuse commons-configuration syntax to insert variable in a property. See http://commons.apache.org/configuration/userguide/howto_basicfeatures.html#V... Good thing is that both commons-configuration and l10n are based on java standard Properties and also that it's the same syntax as other tools to describe properties variable (Maven, Ant, ...) which make it almost a standard. The idea would be that instead of finding if the returned string is a key or not we would see it as a value that can contain variable and which would generally be just the variable. For example we could return "${rendering.macro.include.parameter.document.description}" as include macro "document" field description.

WDYT ?

Thanks, -- Thomas Mortagne

-- Thomas Mortagne