On Wed, Jan 18, 2012 at 9:37 PM, Paul Libbrecht <[email protected]> wrote:

Don't you also need:

#@deprecated "because we stopped this application in release 1.12.2"

#@deprecated "new.key.name: either this or that or that"

?

I'm afraid your syntax is a bit too tiny. I'm definitely encouraging the use of deprecation in i18n messages. Is there or will there be a server to monitor the use of deprecation, and/or analyze it so that they can be removed by proper changes inside the code?? This would be very valuable!

Right now I'm only interested in indicating the new name of the key and that's my only need in a short term. It's very easy to add later other informations like: #@deprecated new.key.name #@since 3.4 old.key.name=Default translation but I would prefer to do it one by one.

paul

Le 18 janv. 2012 à 17:50, Thomas Mortagne a écrit :

...

Hi devs,

Right now renaming a key is a pain if we don't want to loose the existing translations associated to it. Basically it require to rename the key in all languages and reimport all of them on l10n.xwiki.org.

We already have a section in the translation file to indicate which translations are deprecated. The idea is to indicate what is the new name of a deprecated translation key directly in the translation file so that l10n.xwiki.org can automatically copy the translation to the new key when it find a new deprecated key while importing default translation file.

For that we need to decide a syntax to indicate what is the new name of the key.

I propose to do something similar to java and indicate it in a comment like the following:

new.key.name=Default translation

#@deprecated new.key.name old.key.name=Default translation

Here are some other alternatives to "deprecated":

* replacedBy * new

others ?

Here is my +1 for "deprecated", more intuitive for Java developers and it's clear it's a deprecated translation key.

Thanks, -- Thomas Mortagne _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs

_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs

-- Thomas Mortagne

On Thu, Jan 19, 2012 at 8:57 AM, Paul Libbrecht <[email protected]> wrote:

As long as you have a syntax for the future as you sketch below that's ok. Your previous examples didn't show two lines of comments.

I'm surprised, though, that you have the renaming scenario in mind only, it is rarely needed while the "fuzzy renaming" is quite often needed to my experience.

It's not the only thing I have in mind, it's the only thing I plan to do shortly because me have a need for it right now: most of the XE translation keys are going to be renamed while we move the page to separate applications. What do you mean by "fuzzy renaming" ?

What is the flow of deprecation, how would a developer or tester be warned of a deprecated message?

This is not going to change, the current rule is that when you need to rename a translation key you move the old one in a deprecation section of the translation file and we are supposed to remove the key when it's not used anymore in any active branch (we actually forgot to remove lots of older translations when deleting branches). The proposal here is not about how do we deprecate translations, I just want to propose a syntax to indicate what is the new name of a deprecated translations which is not a new concept itself.

paul

Le 19 janv. 2012 à 08:26, Thomas Mortagne a écrit :

...

On Wed, Jan 18, 2012 at 9:37 PM, Paul Libbrecht <[email protected]> wrote:

...

Don't you also need:

#@deprecated "because we stopped this application in release 1.12.2"

#@deprecated "new.key.name: either this or that or that"

?

I'm afraid your syntax is a bit too tiny. I'm definitely encouraging the use of deprecation in i18n messages. Is there or will there be a server to monitor the use of deprecation, and/or analyze it so that they can be removed by proper changes inside the code?? This would be very valuable!

Right now I'm only interested in indicating the new name of the key and that's my only need in a short term. It's very easy to add later other informations like:

#@deprecated new.key.name #@since 3.4 old.key.name=Default translation

but I would prefer to do it one by one.

...

paul

Le 18 janv. 2012 à 17:50, Thomas Mortagne a écrit :

...

Hi devs,

Right now renaming a key is a pain if we don't want to loose the existing translations associated to it. Basically it require to rename the key in all languages and reimport all of them on l10n.xwiki.org.

We already have a section in the translation file to indicate which translations are deprecated. The idea is to indicate what is the new name of a deprecated translation key directly in the translation file so that l10n.xwiki.org can automatically copy the translation to the new key when it find a new deprecated key while importing default translation file.

For that we need to decide a syntax to indicate what is the new name of the key.

I propose to do something similar to java and indicate it in a comment like the following:

new.key.name=Default translation

#@deprecated new.key.name old.key.name=Default translation

Here are some other alternatives to "deprecated":

* replacedBy * new

others ?

Here is my +1 for "deprecated", more intuitive for Java developers and it's clear it's a deprecated translation key.

Thanks, -- Thomas Mortagne _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs

_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs

-- Thomas Mortagne _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs

_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs

-- Thomas Mortagne

On Thu, Jan 19, 2012 at 11:36 AM, Paul Libbrecht <[email protected]> wrote:

Thomas,

Le 19 janv. 2012 à 10:57, Thomas Mortagne a écrit :

...

...

I'm surprised, though, that you have the renaming scenario in mind only, it is rarely needed while the "fuzzy renaming" is quite often needed to my experience.

It's not the only thing I have in mind, it's the only thing I plan to do shortly because me have a need for it right now: most of the XE translation keys are going to be renamed while we move the page to separate applications.

That's clear to me.

...

What do you mean by "fuzzy renaming" ?

It happens more often than it should that some message translations usages need to be refactored to the usage of different keys because of their environment (in this section, one should say it this way, in this section one should say it that way). A deprecation mechanism should be able to support the developer into actualizing to the right keys, chosen from a finite set of suggestions (the new keys).

Examples would be nice ;) Do you mean that the old key is refactored in severals ? In this cases as a key cannot contains a white space in Properties specs we could have: #@deprecated new.key.subname1 new.key.subname2 old.key.name=Default translation

...

...

What is the flow of deprecation, how would a developer or tester be warned of a deprecated message?

This is not going to change, the current rule is that when you need to rename a translation key you move the old one in a deprecation section of the translation file and we are supposed to remove the key when it's not used anymore in any active branch (we actually forgot to remove lots of older translations when deleting branches).

The proposal here is not about how do we deprecate translations, I just want to propose a syntax to indicate what is the new name of a deprecated translations which is not a new concept itself.

The encoding is bound to the target usages and vice versa...

Not sure I understand what you mean.

The restricted view of a key-renaming appears to me as something that could be easily automated leading to an automatic refactoring of the sources. Other deprecation mechanisms cannot be so: the deprecation without replacement can only lead to a developer warning, the deprecation with multiple alternatives can only lead to a warning with suggestion...

Sure it's hard to automate translation copy to the new key when there is 0 or more that one new keys. Do you mean that we need a syntax advanced enough to explain to the l10n wiki or any other tool how to cut the key in peaces to put it in the right keys ?

I'm just trying to see the big picture of the future before settling on the knowledge representation...

Sure, that's why this proposal is for: make sure we go in the right direction. But does not mean we have to do everything at once, just that we need to make sure we don't block the future ;)

paul _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs

-- Thomas Mortagne

On Fri, Jan 20, 2012 at 10:24 AM, Paul Libbrecht <[email protected]> wrote:

Thomas,

Le 19 janv. 2012 à 12:06, Thomas Mortagne a écrit :

...

...

A deprecation mechanism should be able to support the developer into actualizing to the right keys, chosen from a finite set of suggestions (the new keys).

Examples would be nice ;)

Think of redoing a part of "my blabla profile" where "my contributions" are displayed so that it can speak to the third person when the user is not the same: you'd start with a copy of the profile velocity views (pages, vm files), then modify them progressively.

The keys, maybe they were prefixed with "myblabla" would be refactored to be either with "ownblaba" and "othersblabla". Ideally, this should be done in one shot, so no real need of deprecation, but I do not think this can be ensured.

...

Do you mean that the old key is refactored in severals ? In this cases as a key cannot contains a white space in Properties specs we could have:

#@deprecated new.key.subname1 new.key.subname2 old.key.name=Default translation

Fits me perfectly!

...

...

The encoding is bound to the target usages and vice versa... Not sure I understand what you mean.

that's philosophical: I meant we need to envision the usages to make sure the knowledge representation is good engouh.

...

...

The restricted view of a key-renaming appears to me as something that could be easily automated leading to an automatic refactoring of the sources. Other deprecation mechanisms cannot be so: the deprecation without replacement can only lead to a developer warning, the deprecation with multiple alternatives can only lead to a warning with suggestion...

Sure it's hard to automate translation copy to the new key when there is 0 or more that one new keys. Do you mean that we need a syntax advanced enough to explain to the l10n wiki or any other tool how to cut the key in peaces to put it in the right keys ?

I did mean this indeed.

...

...

I'm just trying to see the big picture of the future before settling on the knowledge representation...

Sure, that's why this proposal is for: make sure we go in the right direction. But does not mean we have to do everything at once, just that we need to make sure we don't block the future ;)

We're on the same wavelength.

I think at this point, considering all the cases we've considered, I can say:

+1.

Ok thanks. I will go for #@deprecated new.key.subname1 new.key.subname2 old.key.name=Default translation as first implementation. I will also make sure of the following: * the type of syntax is indicated by a {syntaxid} at the beginning, default being a list of new keys * skip unknown syntax type without complaining. So it allows a large choice of syntaxes to extend the current syntax without breaking anything. For example: #@deprecated {regexp} match="(.*) and (.*)" new.key.subname1=1 new.key.subname2=2 old.key.name=Default translation WDYT ?

I would lover, however, to see what tools are used that use the deprecation.

As I said the first one will be l10n wiki: the goal is to make sure we don't loose translation assigned to the old key when renaming it. When l10n import the default language and see a new deprecated key it's going to copy the translations assigned t the old key on the new key so that when you export again translation from l10n wiki all the translations are now both on the old and new key. On XWiki itself we can imagine printing warning indicating which key to use instead when some code try to get deprecated key translation and even get the translation from the new key instead.

paul _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs

-- Thomas Mortagne

Hi, I`m not entirely sure if this is relevant to the topic at hand or if a similar solution already exists, but since this is the best place for it, I`ll just say it here: Another cool option that Marius suggested, in an offline talk, would be to be able to reference translation keys inside a translation's value. One usecase when this would be very handy is when you create a livetable you have to specify your translation prefix for all the livetable, while you still would have liked to reuse action translations for things like "Delete", "Edit", etc. Instead of adding a new key in your translations that has the value "Delete", you could just say "@platform.index._actions.delete" and reuse an existing key. Back to the deprecation issue of renamed keys at hand, this would be useful as well because you would no longer need to carry the old translation's value and you could just do a: #@deprecated [email protected] This would be very easy to detect in the $msg code and to do a get to the referenced property instead. You could see this as an addition to what you have already proposed/implemented, and not a replacement. I think that, for some usecases, it will make the translations document smaller and less error prone. WDYT? Thanks, Eduard On Fri, Jan 20, 2012 at 6:34 PM, Paul Libbrecht <[email protected]> wrote:

This looks good to me,

I would love to see the second proposal, maybe that'd be a GSOC project if done really completely (including all the workflows, role definition, disrupting/non-disrupting modes...).

My +1.

paul

Le 20 janv. 2012 à 11:41, Thomas Mortagne a écrit :

...

On Fri, Jan 20, 2012 at 10:24 AM, Paul Libbrecht <[email protected]> wrote:

...

Thomas,

Le 19 janv. 2012 à 12:06, Thomas Mortagne a écrit :

...

...

A deprecation mechanism should be able to support the developer into

actualizing to the right keys, chosen from a finite set of suggestions (the new keys).

...

...

Examples would be nice ;)

Think of redoing a part of "my blabla profile" where "my contributions" are displayed so that it can speak to the third person when the user is not the same: you'd start with a copy of the profile velocity views (pages, vm files), then modify them progressively.

The keys, maybe they were prefixed with "myblabla" would be refactored to be either with "ownblaba" and "othersblabla". Ideally, this should be done in one shot, so no real need of deprecation, but I do not think this can be ensured.

...

Do you mean that the old key is refactored in severals ? In this cases as a key cannot contains a white space in Properties specs we could have:

#@deprecated new.key.subname1 new.key.subname2 old.key.name=Default translation

Fits me perfectly!

...

...

The encoding is bound to the target usages and vice versa... Not sure I understand what you mean.

that's philosophical: I meant we need to envision the usages to make sure the knowledge representation is good engouh.

...

...

The restricted view of a key-renaming appears to me as something that could be easily automated leading to an automatic refactoring of the sources. Other deprecation mechanisms cannot be so: the deprecation without replacement can only lead to a developer warning, the deprecation with multiple alternatives can only lead to a warning with suggestion...

Sure it's hard to automate translation copy to the new key when there is 0 or more that one new keys. Do you mean that we need a syntax advanced enough to explain to the l10n wiki or any other tool how to cut the key in peaces to put it in the right keys ?

I did mean this indeed.

...

...

I'm just trying to see the big picture of the future before settling on the knowledge representation...

Sure, that's why this proposal is for: make sure we go in the right direction. But does not mean we have to do everything at once, just that we need to make sure we don't block the future ;)

We're on the same wavelength.

I think at this point, considering all the cases we've considered, I can say:

+1.

Ok thanks.

I will go for

#@deprecated new.key.subname1 new.key.subname2 old.key.name=Default translation

as first implementation.

I will also make sure of the following: * the type of syntax is indicated by a {syntaxid} at the beginning, default being a list of new keys * skip unknown syntax type without complaining. So it allows a large choice of syntaxes to extend the current syntax without breaking anything.

For example:

#@deprecated {regexp} match="(.*) and (.*)" new.key.subname1=1 new.key.subname2=2 old.key.name=Default translation

WDYT ?

...

I would lover, however, to see what tools are used that use the

deprecation.

As I said the first one will be l10n wiki: the goal is to make sure we don't loose translation assigned to the old key when renaming it. When l10n import the default language and see a new deprecated key it's going to copy the translations assigned t the old key on the new key so that when you export again translation from l10n wiki all the translations are now both on the old and new key.

On XWiki itself we can imagine printing warning indicating which key to use instead when some code try to get deprecated key translation and even get the translation from the new key instead.

...

paul _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs

-- Thomas Mortagne _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs

_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs

Thats planned for the new translation module since it's a long time voted need for rendering. On Wed, Mar 7, 2012 at 6:59 PM, Eduard Moraru <[email protected]> wrote:

Hi,

I`m not entirely sure if this is relevant to the topic at hand or if a similar solution already exists, but since this is the best place for it, I`ll just say it here:

Another cool option that Marius suggested, in an offline talk, would be to be able to reference translation keys inside a translation's value.

One usecase when this would be very handy is when you create a livetable you have to specify your translation prefix for all the livetable, while you still would have liked to reuse action translations for things like "Delete", "Edit", etc. Instead of adding a new key in your translations that has the value "Delete", you could just say "@platform.index._actions.delete" and reuse an existing key.

Back to the deprecation issue of renamed keys at hand, this would be useful as well because you would no longer need to carry the old translation's value and you could just do a:

#@deprecated [email protected]

This would be very easy to detect in the $msg code and to do a get to the referenced property instead.

You could see this as an addition to what you have already proposed/implemented, and not a replacement. I think that, for some usecases, it will make the translations document smaller and less error prone.

WDYT?

Thanks, Eduard

On Fri, Jan 20, 2012 at 6:34 PM, Paul Libbrecht <[email protected]> wrote:

...

This looks good to me,

I would love to see the second proposal, maybe that'd be a GSOC project if done really completely (including all the workflows, role definition, disrupting/non-disrupting modes...).

My +1.

paul

Le 20 janv. 2012 à 11:41, Thomas Mortagne a écrit :

...

On Fri, Jan 20, 2012 at 10:24 AM, Paul Libbrecht <[email protected]> wrote:

...

Thomas,

Le 19 janv. 2012 à 12:06, Thomas Mortagne a écrit :

...

...

A deprecation mechanism should be able to support the developer into

actualizing to the right keys, chosen from a finite set of suggestions (the new keys).

...

...

Examples would be nice ;)

Think of redoing a part of "my blabla profile" where "my contributions" are displayed so that it can speak to the third person when the user is not the same: you'd start with a copy of the profile velocity views (pages, vm files), then modify them progressively.

The keys, maybe they were prefixed with "myblabla" would be refactored to be either with "ownblaba" and "othersblabla". Ideally, this should be done in one shot, so no real need of deprecation, but I do not think this can be ensured.

...

Do you mean that the old key is refactored in severals ? In this cases as a key cannot contains a white space in Properties specs we could have:

#@deprecated new.key.subname1 new.key.subname2 old.key.name=Default translation

Fits me perfectly!

...

...

The encoding is bound to the target usages and vice versa... Not sure I understand what you mean.

that's philosophical: I meant we need to envision the usages to make sure the knowledge representation is good engouh.

...

...

The restricted view of a key-renaming appears to me as something that could be easily automated leading to an automatic refactoring of the sources. Other deprecation mechanisms cannot be so: the deprecation without replacement can only lead to a developer warning, the deprecation with multiple alternatives can only lead to a warning with suggestion...

Sure it's hard to automate translation copy to the new key when there is 0 or more that one new keys. Do you mean that we need a syntax advanced enough to explain to the l10n wiki or any other tool how to cut the key in peaces to put it in the right keys ?

I did mean this indeed.

...

...

I'm just trying to see the big picture of the future before settling on the knowledge representation...

Sure, that's why this proposal is for: make sure we go in the right direction. But does not mean we have to do everything at once, just that we need to make sure we don't block the future ;)

We're on the same wavelength.

I think at this point, considering all the cases we've considered, I can say:

+1.

Ok thanks.

I will go for

#@deprecated new.key.subname1 new.key.subname2 old.key.name=Default translation

as first implementation.

I will also make sure of the following: * the type of syntax is indicated by a {syntaxid} at the beginning, default being a list of new keys * skip unknown syntax type without complaining. So it allows a large choice of syntaxes to extend the current syntax without breaking anything.

For example:

#@deprecated {regexp} match="(.*) and (.*)" new.key.subname1=1 new.key.subname2=2 old.key.name=Default translation

WDYT ?

...

I would lover, however, to see what tools are used that use the

deprecation.

As I said the first one will be l10n wiki: the goal is to make sure we don't loose translation assigned to the old key when renaming it. When l10n import the default language and see a new deprecated key it's going to copy the translations assigned t the old key on the new key so that when you export again translation from l10n wiki all the translations are now both on the old and new key.

On XWiki itself we can imagine printing warning indicating which key to use instead when some code try to get deprecated key translation and even get the translation from the new key instead.

...

paul _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs

-- Thomas Mortagne _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs

_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs

_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs

-- Thomas Mortagne