[Proposal] Improve translations best practices

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

[Proposal] Improve translations best practices

caubin
Hi everyone !

So, recently I have been dealing with a module that uses two kind of
translation strings.

- "Static" translations : the title of a block, a xHint, … the
translation key itself is not meant to be changed over time.
- "Dynamic" translations : things like :
  - mymodule.component.<componentId>.name
  - mymodule.component.<componentId>.description
  Those are translation strings that depend on a parameter (here
componentId) that can be part of a list.

If you want a better in-context example, check out this gist :
https://gist.github.com/aubincleme/19edb249082185deedc8ec36fe354d42

Currently, we don’t have a lot of best practices regarding the
translation keys (see the doc :
http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#HTranslationBestPractices),
so it may b nice to think about improving them.

Here are some proposals :

* For translation keys used for a livetable, we could use the following
: <prefix>.<liveTableId>Table.<columnName> or
<prefix>.table.<columnName> if the livetable doesn’t have a specific id.

* If we deal with "dynamic" translation keys, it would be nice to mark
them as different from the others with an underscore (_) prefix, or a
specific keyword.

WDYT ?

Thanks,
Clément
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Improve translations best practices

Marius Dumitru Florea
On Wed, Aug 23, 2017 at 11:23 AM, Clément Aubin <[hidden email]>
wrote:

> Hi everyone !
>
> So, recently I have been dealing with a module that uses two kind of
> translation strings.
>
> - "Static" translations : the title of a block, a xHint, … the
> translation key itself is not meant to be changed over time.
> - "Dynamic" translations : things like :
>   - mymodule.component.<componentId>.name
>   - mymodule.component.<componentId>.description
>   Those are translation strings that depend on a parameter (here
> componentId) that can be part of a list.
>
> If you want a better in-context example, check out this gist :
> https://gist.github.com/aubincleme/19edb249082185deedc8ec36fe354d42
>
> Currently, we don’t have a lot of best practices regarding the
> translation keys (see the doc :
> http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#
> HTranslationBestPractices),
> so it may b nice to think about improving them.
>

We have quite a few best practice rules, but on
http://dev.xwiki.org/xwiki/bin/view/Community/L10N%20Conventions , which is
linked from the place you mentioned.


>
> Here are some proposals :
>
> * For translation keys used for a livetable, we could use the following
> : <prefix>.<liveTableId>Table.<columnName> or
> <prefix>.table.<columnName> if the livetable doesn’t have a specific id.
>
> * If we deal with "dynamic" translation keys, it would be nice to mark
> them as different from the others with an underscore (_) prefix, or a
> specific keyword.
>
> WDYT ?
>
> Thanks,
> Clément
>
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Improve translations best practices

vmassol
Administrator
Hi Clement,

> On 23 Aug 2017, at 14:45, Marius Dumitru Florea <[hidden email]> wrote:
>
> On Wed, Aug 23, 2017 at 11:23 AM, Clément Aubin <[hidden email]>
> wrote:
>
>> Hi everyone !
>>
>> So, recently I have been dealing with a module that uses two kind of
>> translation strings.
>>
>> - "Static" translations : the title of a block, a xHint, … the
>> translation key itself is not meant to be changed over time.
>> - "Dynamic" translations : things like :
>>  - mymodule.component.<componentId>.name
>>  - mymodule.component.<componentId>.description
>>  Those are translation strings that depend on a parameter (here
>> componentId) that can be part of a list.
>>
>> If you want a better in-context example, check out this gist :
>> https://gist.github.com/aubincleme/19edb249082185deedc8ec36fe354d42
>>
>> Currently, we don’t have a lot of best practices regarding the
>> translation keys (see the doc :
>> http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#
>> HTranslationBestPractices),
>> so it may b nice to think about improving them.
>>
>
> We have quite a few best practice rules, but on
> http://dev.xwiki.org/xwiki/bin/view/Community/L10N%20Conventions , which is
> linked from the place you mentioned.

Is your proposal still valid in light of what exists at http://dev.xwiki.org/xwiki/bin/view/Community/L10N%20Conventions ?

Thanks
-Vincent


>
>
>>
>> Here are some proposals :
>>
>> * For translation keys used for a livetable, we could use the following
>> : <prefix>.<liveTableId>Table.<columnName> or
>> <prefix>.table.<columnName> if the livetable doesn’t have a specific id.
>>
>> * If we deal with "dynamic" translation keys, it would be nice to mark
>> them as different from the others with an underscore (_) prefix, or a
>> specific keyword.
>>
>> WDYT ?
>>
>> Thanks,
>> Clément

Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Improve translations best practices

caubin
Hi,

On 08/28/2017 05:43 PM, Vincent Massol wrote:

> Hi Clement,
>
>> On 23 Aug 2017, at 14:45, Marius Dumitru Florea <[hidden email]> wrote:
>>
>> On Wed, Aug 23, 2017 at 11:23 AM, Clément Aubin <[hidden email]>
>> wrote:
>>
>>> Hi everyone !
>>>
>>> So, recently I have been dealing with a module that uses two kind of
>>> translation strings.
>>>
>>> - "Static" translations : the title of a block, a xHint, … the
>>> translation key itself is not meant to be changed over time.
>>> - "Dynamic" translations : things like :
>>>  - mymodule.component.<componentId>.name
>>>  - mymodule.component.<componentId>.description
>>>  Those are translation strings that depend on a parameter (here
>>> componentId) that can be part of a list.
>>>
>>> If you want a better in-context example, check out this gist :
>>> https://gist.github.com/aubincleme/19edb249082185deedc8ec36fe354d42
>>>
>>> Currently, we don’t have a lot of best practices regarding the
>>> translation keys (see the doc :
>>> http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#
>>> HTranslationBestPractices),
>>> so it may b nice to think about improving them.
>>>
>>
>> We have quite a few best practice rules, but on
>> http://dev.xwiki.org/xwiki/bin/view/Community/L10N%20Conventions , which is
>> linked from the place you mentioned.
>
> Is your proposal still valid in light of what exists at http://dev.xwiki.org/xwiki/bin/view/Community/L10N%20Conventions ?

Well, though the L10N conventions lights up a lot of the questions I had
about translations (it also lights up the fact that I'm still not able
to read properly documentation in order to find the correct link),
AFAICS, we don't talk about the rules related to the naming of (what I
called earlier) "Dynamic" translations.

Therefore, one question would be : do we have enough "Dynamic"
translations in the platform in order to decide of a best practice, or
is it just a special case ?

Also, we don’t have any guidelines about naming the translations of
column livetables, though those are quite frequent nowadays in the XWiki
UI. Maybe we could add another bullet point in
http://dev.xwiki.org/xwiki/bin/view/Community/L10N%20Conventions#HRulesfornamingelements
or
http://dev.xwiki.org/xwiki/bin/view/Community/L10N%20Conventions#HRulesforstandardformelements
(but I don’t think that a livetable should be considered as a _form
element_).

Thanks,
Clément

> Thanks
> -Vincent
>
>
>>
>>
>>>
>>> Here are some proposals :
>>>
>>> * For translation keys used for a livetable, we could use the following
>>> : <prefix>.<liveTableId>Table.<columnName> or
>>> <prefix>.table.<columnName> if the livetable doesn’t have a specific id.
>>>
>>> * If we deal with "dynamic" translation keys, it would be nice to mark
>>> them as different from the others with an underscore (_) prefix, or a
>>> specific keyword.
>>>
>>> WDYT ?
>>>
>>> Thanks,
>>> Clément
>
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Improve translations best practices

Sergiu Dumitriu-3
I wouldn't call them "dynamic" translation keys, but we do have plenty
of auto-translated elements, based on different rules, and I agree that
these rules are not well documented at all. The best example of this
kind of keys is how XProperty pretty names are translated, and
fortunately this is documented on
http://dev.xwiki.org/xwiki/bin/view/Community/L10N%20Conventions#HTranslatingXClasses

Still, this is something that isn't generally documented for other
places where translations are tried automatically. And the problem isn't
in identifying which keys are supposed to be dynamic, but letting users
know that things are translatable.

IMHO, the same general rules for key formats should apply to dynamic
keys. And in each case, the final naming scheme depends a lot on the
specific place where they are used.

As for discoverability, I'd say that a new section in the application
description on e.x.o would be the perfect place for this. For example,
on
http://extensions.xwiki.org/xwiki/bin/view/Extension/Livetable%20Application
we could add a "Translations" section where we say that each column
title can be automatically translated by translating keys in the format:

<tableId>.livetable.<columnId>

On 08/28/2017 05:42 PM, Clément Aubin wrote:

> Hi,
>
> On 08/28/2017 05:43 PM, Vincent Massol wrote:
>> Hi Clement,
>>
>>> On 23 Aug 2017, at 14:45, Marius Dumitru Florea <[hidden email]> wrote:
>>>
>>> On Wed, Aug 23, 2017 at 11:23 AM, Clément Aubin <[hidden email]>
>>> wrote:
>>>
>>>> Hi everyone !
>>>>
>>>> So, recently I have been dealing with a module that uses two kind of
>>>> translation strings.
>>>>
>>>> - "Static" translations : the title of a block, a xHint, … the
>>>> translation key itself is not meant to be changed over time.
>>>> - "Dynamic" translations : things like :
>>>>  - mymodule.component.<componentId>.name
>>>>  - mymodule.component.<componentId>.description
>>>>  Those are translation strings that depend on a parameter (here
>>>> componentId) that can be part of a list.
>>>>
>>>> If you want a better in-context example, check out this gist :
>>>> https://gist.github.com/aubincleme/19edb249082185deedc8ec36fe354d42
>>>>
>>>> Currently, we don’t have a lot of best practices regarding the
>>>> translation keys (see the doc :
>>>> http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#
>>>> HTranslationBestPractices),
>>>> so it may b nice to think about improving them.
>>>>
>>>
>>> We have quite a few best practice rules, but on
>>> http://dev.xwiki.org/xwiki/bin/view/Community/L10N%20Conventions , which is
>>> linked from the place you mentioned.
>>
>> Is your proposal still valid in light of what exists at http://dev.xwiki.org/xwiki/bin/view/Community/L10N%20Conventions ?
>
> Well, though the L10N conventions lights up a lot of the questions I had
> about translations (it also lights up the fact that I'm still not able
> to read properly documentation in order to find the correct link),
> AFAICS, we don't talk about the rules related to the naming of (what I
> called earlier) "Dynamic" translations.
>
> Therefore, one question would be : do we have enough "Dynamic"
> translations in the platform in order to decide of a best practice, or
> is it just a special case ?
>
> Also, we don’t have any guidelines about naming the translations of
> column livetables, though those are quite frequent nowadays in the XWiki
> UI. Maybe we could add another bullet point in
> http://dev.xwiki.org/xwiki/bin/view/Community/L10N%20Conventions#HRulesfornamingelements
> or
> http://dev.xwiki.org/xwiki/bin/view/Community/L10N%20Conventions#HRulesforstandardformelements
> (but I don’t think that a livetable should be considered as a _form
> element_).
>
> Thanks,
> Clément
>
>> Thanks
>> -Vincent
>>
>>
>>>
>>>
>>>>
>>>> Here are some proposals :
>>>>
>>>> * For translation keys used for a livetable, we could use the following
>>>> : <prefix>.<liveTableId>Table.<columnName> or
>>>> <prefix>.table.<columnName> if the livetable doesn’t have a specific id.
>>>>
>>>> * If we deal with "dynamic" translation keys, it would be nice to mark
>>>> them as different from the others with an underscore (_) prefix, or a
>>>> specific keyword.
>>>>
>>>> WDYT ?
>>>>
>>>> Thanks,
>>>> Clément
>>


--
Sergiu Dumitriu
http://purl.org/net/sergiu