[Proposal] L10N Conventions

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

[Proposal] L10N Conventions

Sergiu Dumitriu-3
Hi devs,

I've written some conventions for translation messages at
http://dev.xwiki.org/xwiki/bin/view/Community/L10N+Conventions

Please provide feedback, since we terribly lack some proper rules here,
and there aren't two applications that use the same conventions. Now
that we have support for modular translation documents, it's a good time
to clean up translations and move things out of ApplicationProperties
into each application.

--
Sergiu Dumitriu
http://purl.org/net/sergiu
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] L10N Conventions

Marius Dumitru Florea
Big +1. We should link this page from l10n.xwiki.org.

Thanks,
Marius

On Sat, Nov 24, 2012 at 4:55 AM, Sergiu Dumitriu <[hidden email]> wrote:

> Hi devs,
>
> I've written some conventions for translation messages at
> http://dev.xwiki.org/xwiki/bin/view/Community/L10N+Conventions
>
> Please provide feedback, since we terribly lack some proper rules here,
> and there aren't two applications that use the same conventions. Now
> that we have support for modular translation documents, it's a good time
> to clean up translations and move things out of ApplicationProperties
> into each application.
>
> --
> Sergiu Dumitriu
> http://purl.org/net/sergiu
> _______________________________________________
> devs mailing list
> [hidden email]
> http://lists.xwiki.org/mailman/listinfo/devs
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] L10N Conventions

Roman Muntyanu
In reply to this post by Sergiu Dumitriu-3
As translation contributor: +1 for the translation rules part.

-----Original Message-----
From: [hidden email] [mailto:[hidden email]] On Behalf Of Sergiu Dumitriu
Sent: Saturday, November 24, 2012 04:55 AM
To: XWiki Developers
Subject: [xwiki-devs] [Proposal] L10N Conventions

Hi devs,

I've written some conventions for translation messages at http://dev.xwiki.org/xwiki/bin/view/Community/L10N+Conventions

Please provide feedback, since we terribly lack some proper rules here, and there aren't two applications that use the same conventions. Now that we have support for modular translation documents, it's a good time to clean up translations and move things out of ApplicationProperties into each application.

--
Sergiu Dumitriu
http://purl.org/net/sergiu
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] L10N Conventions

Thomas Mortagne
Administrator
In reply to this post by Sergiu Dumitriu-3
On Sat, Nov 24, 2012 at 3:55 AM, Sergiu Dumitriu <[hidden email]> wrote:

> Hi devs,
>
> I've written some conventions for translation messages at
> http://dev.xwiki.org/xwiki/bin/view/Community/L10N+Conventions
>
> Please provide feedback, since we terribly lack some proper rules here,
> and there aren't two applications that use the same conventions.


Looks good in general. I would not insist to much on the fact that XWiki
use MessageTool, that's the currently supported syntax but it's just one
syntax from new l10n module point of view and I think we should move away
from it when we will have some time and introduce a new syntax (we need
variables, the way we deal with ' character is not very nice, etc.).

Now
> that we have support for modular translation documents, it's a good time
> to clean up translations and move things out of ApplicationProperties
> into each application.
>

Still require https://jira.xwiki.org/browse/XWIKI-8263 to be fully modular
(thinking about java macros for example) but should be OK in 4.4.


> --
> Sergiu Dumitriu
> http://purl.org/net/sergiu
> _______________________________________________
> devs mailing list
> [hidden email]
> http://lists.xwiki.org/mailman/listinfo/devs
>



--
Thomas Mortagne
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] L10N Conventions

Eduard Moraru
In reply to this post by Sergiu Dumitriu-3
Hi Sergiu,

Great work on the translations best practices, as we really needed such a
document.

Regarding the naming convention, I`m not very happy with the fact that,
AFAIK, we have already [1] voted on this topic in the past.
Now I know that not everybody is doing it, but I, for one, have already
added a good number of translations based on this voted convention.

-0.1 for the naming convention (Key format section), until we clear things
out.
+1 for the rest of the document.

Thanks,
Eduard

----------
[1] http://xwiki.markmail.org/thread/6qn6peyehxr73le7


On Sat, Nov 24, 2012 at 4:55 AM, Sergiu Dumitriu <[hidden email]> wrote:

> Hi devs,
>
> I've written some conventions for translation messages at
> http://dev.xwiki.org/xwiki/bin/view/Community/L10N+Conventions
>
> Please provide feedback, since we terribly lack some proper rules here,
> and there aren't two applications that use the same conventions. Now
> that we have support for modular translation documents, it's a good time
> to clean up translations and move things out of ApplicationProperties
> into each application.
>
> --
> Sergiu Dumitriu
> http://purl.org/net/sergiu
> _______________________________________________
> devs mailing list
> [hidden email]
> http://lists.xwiki.org/mailman/listinfo/devs
>
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] L10N Conventions

Sergiu Dumitriu-3
On 11/26/2012 08:26 AM, Eduard Moraru wrote:
> Hi Sergiu,
>
> Great work on the translations best practices, as we really needed such a
> document.
>
> Regarding the naming convention, I`m not very happy with the fact that,
> AFAIK, we have already [1] voted on this topic in the past.
> Now I know that not everybody is doing it, but I, for one, have already
> added a good number of translations based on this voted convention.

Ah, thanks for the link, I tried to find it but my search skills are
getting rusty...

I missed the previous vote, I would have said -1 to the
allCamelCasePropertyNamesInOnePart.

IMO, using dots to create multiple parts is better because:
- it's easier to read
- it provides fine-grained "namespacing", and proper namespacing is
always a good thing
- I have some ideas for improving the l10n process that would need this
namespacing, but that's for later

For example, what does trashAttachmentsActionsCannotRestoreTooltip refer
to? Splitting it into trash.attachments.actions.cannotRestore.tooltip
makes it easier to understand from the first read. Same about
liveTableEditorClassFieldColumnGroupLabel.

Don't worry about existing keys, as I said, there are few applications
that use the same set of rules, and whatever standard we pick, we'll
still have to "fix" a very large portion of keys.

> -0.1 for the naming convention (Key format section), until we clear things
> out.
> +1 for the rest of the document.
>
> Thanks,
> Eduard
>
> ----------
> [1] http://xwiki.markmail.org/thread/6qn6peyehxr73le7
>
>
> On Sat, Nov 24, 2012 at 4:55 AM, Sergiu Dumitriu <[hidden email]> wrote:
>
>> Hi devs,
>>
>> I've written some conventions for translation messages at
>> http://dev.xwiki.org/xwiki/bin/view/Community/L10N+Conventions
>>
>> Please provide feedback, since we terribly lack some proper rules here,
>> and there aren't two applications that use the same conventions. Now
>> that we have support for modular translation documents, it's a good time
>> to clean up translations and move things out of ApplicationProperties
>> into each application.


--
Sergiu Dumitriu
http://purl.org/net/sergiu
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] L10N Conventions

vmassol
Administrator
Hi Sergiu,

Could you please move your document to the Draft section since it's not normal to see it in the best practices since it's not been agreed about yet?

See below

On Nov 26, 2012, at 8:35 PM, Sergiu Dumitriu <[hidden email]> wrote:

> On 11/26/2012 08:26 AM, Eduard Moraru wrote:
>> Hi Sergiu,
>>
>> Great work on the translations best practices, as we really needed such a
>> document.
>>
>> Regarding the naming convention, I`m not very happy with the fact that,
>> AFAIK, we have already [1] voted on this topic in the past.
>> Now I know that not everybody is doing it, but I, for one, have already
>> added a good number of translations based on this voted convention.
>
> Ah, thanks for the link, I tried to find it but my search skills are
> getting rusty...
>
> I missed the previous vote, I would have said -1 to the
> allCamelCasePropertyNamesInOnePart.

Also we've been using this for a long time now so please don't change it just now (that would require another vote thread) :)

BTW it's been documented too at http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#HTranslationPropertyNaming

Thanks
-Vincent

PS: I've not read your document yet (need to finish the release first :))

> IMO, using dots to create multiple parts is better because:
> - it's easier to read
> - it provides fine-grained "namespacing", and proper namespacing is
> always a good thing
> - I have some ideas for improving the l10n process that would need this
> namespacing, but that's for later
>
> For example, what does trashAttachmentsActionsCannotRestoreTooltip refer
> to? Splitting it into trash.attachments.actions.cannotRestore.tooltip
> makes it easier to understand from the first read. Same about
> liveTableEditorClassFieldColumnGroupLabel.
>
> Don't worry about existing keys, as I said, there are few applications
> that use the same set of rules, and whatever standard we pick, we'll
> still have to "fix" a very large portion of keys.
>
>> -0.1 for the naming convention (Key format section), until we clear things
>> out.
>> +1 for the rest of the document.
>>
>> Thanks,
>> Eduard
>>
>> ----------
>> [1] http://xwiki.markmail.org/thread/6qn6peyehxr73le7
>>
>>
>> On Sat, Nov 24, 2012 at 4:55 AM, Sergiu Dumitriu <[hidden email]> wrote:
>>
>>> Hi devs,
>>>
>>> I've written some conventions for translation messages at
>>> http://dev.xwiki.org/xwiki/bin/view/Community/L10N+Conventions
>>>
>>> Please provide feedback, since we terribly lack some proper rules here,
>>> and there aren't two applications that use the same conventions. Now
>>> that we have support for modular translation documents, it's a good time
>>> to clean up translations and move things out of ApplicationProperties
>>> into each application.

_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] L10N Conventions

Marius Dumitru Florea
On Mon, Nov 26, 2012 at 10:44 PM, Vincent Massol <[hidden email]> wrote:

> Hi Sergiu,
>
> Could you please move your document to the Draft section since it's not normal to see it in the best practices since it's not been agreed about yet?
>
> See below
>
> On Nov 26, 2012, at 8:35 PM, Sergiu Dumitriu <[hidden email]> wrote:
>
>> On 11/26/2012 08:26 AM, Eduard Moraru wrote:
>>> Hi Sergiu,
>>>
>>> Great work on the translations best practices, as we really needed such a
>>> document.
>>>
>>> Regarding the naming convention, I`m not very happy with the fact that,
>>> AFAIK, we have already [1] voted on this topic in the past.
>>> Now I know that not everybody is doing it, but I, for one, have already
>>> added a good number of translations based on this voted convention.
>>
>> Ah, thanks for the link, I tried to find it but my search skills are
>> getting rusty...
>>
>> I missed the previous vote, I would have said -1 to the
>> allCamelCasePropertyNamesInOnePart.
>

> Also we've been using this for a long time now so please don't change it just now (that would require another vote thread) :)

It was voted but we didn't really use it.. I agree with Sergiu that
more than 2 namespaces (project and module) are needed. My vote is
still +1 for Sergiu's proposal (and I was aware of the previous vote
when I first reply).

Thanks,
Marius

>
> BTW it's been documented too at http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#HTranslationPropertyNaming
>
> Thanks
> -Vincent
>
> PS: I've not read your document yet (need to finish the release first :))
>
>> IMO, using dots to create multiple parts is better because:
>> - it's easier to read
>> - it provides fine-grained "namespacing", and proper namespacing is
>> always a good thing
>> - I have some ideas for improving the l10n process that would need this
>> namespacing, but that's for later
>>
>> For example, what does trashAttachmentsActionsCannotRestoreTooltip refer
>> to? Splitting it into trash.attachments.actions.cannotRestore.tooltip
>> makes it easier to understand from the first read. Same about
>> liveTableEditorClassFieldColumnGroupLabel.
>>
>> Don't worry about existing keys, as I said, there are few applications
>> that use the same set of rules, and whatever standard we pick, we'll
>> still have to "fix" a very large portion of keys.
>>
>>> -0.1 for the naming convention (Key format section), until we clear things
>>> out.
>>> +1 for the rest of the document.
>>>
>>> Thanks,
>>> Eduard
>>>
>>> ----------
>>> [1] http://xwiki.markmail.org/thread/6qn6peyehxr73le7
>>>
>>>
>>> On Sat, Nov 24, 2012 at 4:55 AM, Sergiu Dumitriu <[hidden email]> wrote:
>>>
>>>> Hi devs,
>>>>
>>>> I've written some conventions for translation messages at
>>>> http://dev.xwiki.org/xwiki/bin/view/Community/L10N+Conventions
>>>>
>>>> Please provide feedback, since we terribly lack some proper rules here,
>>>> and there aren't two applications that use the same conventions. Now
>>>> that we have support for modular translation documents, it's a good time
>>>> to clean up translations and move things out of ApplicationProperties
>>>> into each application.
>
> _______________________________________________
> devs mailing list
> [hidden email]
> http://lists.xwiki.org/mailman/listinfo/devs
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] L10N Conventions

vmassol
Administrator

On Nov 27, 2012, at 9:11 AM, Marius Dumitru Florea <[hidden email]> wrote:

> On Mon, Nov 26, 2012 at 10:44 PM, Vincent Massol <[hidden email]> wrote:
>> Hi Sergiu,
>>
>> Could you please move your document to the Draft section since it's not normal to see it in the best practices since it's not been agreed about yet?
>>
>> See below
>>
>> On Nov 26, 2012, at 8:35 PM, Sergiu Dumitriu <[hidden email]> wrote:
>>
>>> On 11/26/2012 08:26 AM, Eduard Moraru wrote:
>>>> Hi Sergiu,
>>>>
>>>> Great work on the translations best practices, as we really needed such a
>>>> document.
>>>>
>>>> Regarding the naming convention, I`m not very happy with the fact that,
>>>> AFAIK, we have already [1] voted on this topic in the past.
>>>> Now I know that not everybody is doing it, but I, for one, have already
>>>> added a good number of translations based on this voted convention.
>>>
>>> Ah, thanks for the link, I tried to find it but my search skills are
>>> getting rusty...
>>>
>>> I missed the previous vote, I would have said -1 to the
>>> allCamelCasePropertyNamesInOnePart.
>>
>
>> Also we've been using this for a long time now so please don't change it just now (that would require another vote thread) :)
>
> It was voted but we didn't really use it..

I don't agree. I've been using it 100% of the time and others too. Anyone not using it is not following the best practice and that's pretty bad.

> I agree with Sergiu that
> more than 2 namespaces (project and module) are needed. My vote is
> still +1 for Sergiu's proposal (and I was aware of the previous vote
> when I first reply).

There's no vote so you cannot be +1. If sergiu wants to change the current way we name transation key she should send a vote.

I've moved his proposal page to http://dev.xwiki.org/xwiki/bin/view/Drafts/L10N+Conventions so that it's not confused as something established.

Thanks
-Vincent

> Thanks,
> Marius
>
>>
>> BTW it's been documented too at http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#HTranslationPropertyNaming
>>
>> Thanks
>> -Vincent
>>
>> PS: I've not read your document yet (need to finish the release first :))
>>
>>> IMO, using dots to create multiple parts is better because:
>>> - it's easier to read
>>> - it provides fine-grained "namespacing", and proper namespacing is
>>> always a good thing
>>> - I have some ideas for improving the l10n process that would need this
>>> namespacing, but that's for later
>>>
>>> For example, what does trashAttachmentsActionsCannotRestoreTooltip refer
>>> to? Splitting it into trash.attachments.actions.cannotRestore.tooltip
>>> makes it easier to understand from the first read. Same about
>>> liveTableEditorClassFieldColumnGroupLabel.
>>>
>>> Don't worry about existing keys, as I said, there are few applications
>>> that use the same set of rules, and whatever standard we pick, we'll
>>> still have to "fix" a very large portion of keys.
>>>
>>>> -0.1 for the naming convention (Key format section), until we clear things
>>>> out.
>>>> +1 for the rest of the document.
>>>>
>>>> Thanks,
>>>> Eduard
>>>>
>>>> ----------
>>>> [1] http://xwiki.markmail.org/thread/6qn6peyehxr73le7
>>>>
>>>>
>>>> On Sat, Nov 24, 2012 at 4:55 AM, Sergiu Dumitriu <[hidden email]> wrote:
>>>>
>>>>> Hi devs,
>>>>>
>>>>> I've written some conventions for translation messages at
>>>>> http://dev.xwiki.org/xwiki/bin/view/Community/L10N+Conventions
>>>>>
>>>>> Please provide feedback, since we terribly lack some proper rules here,
>>>>> and there aren't two applications that use the same conventions. Now
>>>>> that we have support for modular translation documents, it's a good time
>>>>> to clean up translations and move things out of ApplicationProperties
>>>>> into each application.

_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] L10N Conventions

Jean-Vincent Drean
In reply to this post by Marius Dumitru Florea
On Tue, Nov 27, 2012 at 9:11 AM, Marius Dumitru Florea <
[hidden email]> wrote:

> It was voted but we didn't really use it.. I agree with Sergiu that
> more than 2 namespaces (project and module) are needed. My vote is
> still +1 for Sergiu's proposal (and I was aware of the previous vote
> when I first reply).
>

I agree that having more than 2 namespaces is very useful.
I used the 2 namespaces rule once or twice, but very reluctantly.

JV.
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] L10N Conventions

vmassol
Administrator
In reply to this post by vmassol

On Nov 27, 2012, at 10:51 AM, Vincent Massol <[hidden email]> wrote:

>
> On Nov 27, 2012, at 9:11 AM, Marius Dumitru Florea <[hidden email]> wrote:
>
>> On Mon, Nov 26, 2012 at 10:44 PM, Vincent Massol <[hidden email]> wrote:
>>> Hi Sergiu,
>>>
>>> Could you please move your document to the Draft section since it's not normal to see it in the best practices since it's not been agreed about yet?
>>>
>>> See below
>>>
>>> On Nov 26, 2012, at 8:35 PM, Sergiu Dumitriu <[hidden email]> wrote:
>>>
>>>> On 11/26/2012 08:26 AM, Eduard Moraru wrote:
>>>>> Hi Sergiu,
>>>>>
>>>>> Great work on the translations best practices, as we really needed such a
>>>>> document.
>>>>>
>>>>> Regarding the naming convention, I`m not very happy with the fact that,
>>>>> AFAIK, we have already [1] voted on this topic in the past.
>>>>> Now I know that not everybody is doing it, but I, for one, have already
>>>>> added a good number of translations based on this voted convention.
>>>>
>>>> Ah, thanks for the link, I tried to find it but my search skills are
>>>> getting rusty...
>>>>
>>>> I missed the previous vote, I would have said -1 to the
>>>> allCamelCasePropertyNamesInOnePart.
>>>
>>
>>> Also we've been using this for a long time now so please don't change it just now (that would require another vote thread) :)
>>
>> It was voted but we didn't really use it..
>
> I don't agree. I've been using it 100% of the time and others too. Anyone not using it is not following the best practice and that's pretty bad.
>
>> I agree with Sergiu that
>> more than 2 namespaces (project and module) are needed. My vote is
>> still +1 for Sergiu's proposal (and I was aware of the previous vote
>> when I first reply).
>
> There's no vote so you cannot be +1. If sergiu wants to change the current way we name transation key she should send a vote.

I meant "he" of course :)

-Vincent

> I've moved his proposal page to http://dev.xwiki.org/xwiki/bin/view/Drafts/L10N+Conventions so that it's not confused as something established.
>
> Thanks
> -Vincent
>
>> Thanks,
>> Marius
>>
>>>
>>> BTW it's been documented too at http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#HTranslationPropertyNaming
>>>
>>> Thanks
>>> -Vincent
>>>
>>> PS: I've not read your document yet (need to finish the release first :))
>>>
>>>> IMO, using dots to create multiple parts is better because:
>>>> - it's easier to read
>>>> - it provides fine-grained "namespacing", and proper namespacing is
>>>> always a good thing
>>>> - I have some ideas for improving the l10n process that would need this
>>>> namespacing, but that's for later
>>>>
>>>> For example, what does trashAttachmentsActionsCannotRestoreTooltip refer
>>>> to? Splitting it into trash.attachments.actions.cannotRestore.tooltip
>>>> makes it easier to understand from the first read. Same about
>>>> liveTableEditorClassFieldColumnGroupLabel.
>>>>
>>>> Don't worry about existing keys, as I said, there are few applications
>>>> that use the same set of rules, and whatever standard we pick, we'll
>>>> still have to "fix" a very large portion of keys.
>>>>
>>>>> -0.1 for the naming convention (Key format section), until we clear things
>>>>> out.
>>>>> +1 for the rest of the document.
>>>>>
>>>>> Thanks,
>>>>> Eduard
>>>>>
>>>>> ----------
>>>>> [1] http://xwiki.markmail.org/thread/6qn6peyehxr73le7
>>>>>
>>>>>
>>>>> On Sat, Nov 24, 2012 at 4:55 AM, Sergiu Dumitriu <[hidden email]> wrote:
>>>>>
>>>>>> Hi devs,
>>>>>>
>>>>>> I've written some conventions for translation messages at
>>>>>> http://dev.xwiki.org/xwiki/bin/view/Community/L10N+Conventions
>>>>>>
>>>>>> Please provide feedback, since we terribly lack some proper rules here,
>>>>>> and there aren't two applications that use the same conventions. Now
>>>>>> that we have support for modular translation documents, it's a good time
>>>>>> to clean up translations and move things out of ApplicationProperties
>>>>>> into each application.
>

_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] L10N Conventions

vmassol
Administrator
In reply to this post by Sergiu Dumitriu-3
Hi Sergiu,

Good initiative! I've now taken the time to read your proposal. Some comments:

* Regarding the change of key format, I believe this requires a separate VOTE  email since the previous format was already voted (and the result is documented at http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#HTranslationPropertyNaming ). The VOTE would also needs to mention what we do for existing keys and how do we ensure the new format would be used properly (it's quite complex). I also believe we should maybe not put the top level module as prefix since we now have a single product which is platform/XE and having this prefix makes the key more brittle. For the same reason that we don't use "platform" as a prefix in the package name for java classes. In your VOTE email also explain more in detail when to use camel case vs a dot. For example:  error.invalidFormat vs error.format.invalid.

* The rest seems ok to me with good practices

* One note: we already have some rules regarding deprecations, see http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#HTranslationPropertyDeprecations

* Your proposal is missing a section about deciding when to use translations keys and when to use translated documents. For example if I have a page like this:

"
<2 sentences here>

{{velocity}}
#if ($hasAdmin)
  // do something here
#end
{{/velocity}}

<some other sentence>
"

Should it be using translations keys or translation documents with possibly a refactoring to move the velocity code in another document, resulting in minimal macro usage:

"
<2 sentences here>

{{include reference="document containing the code"/}}

<some other sentence>
"

?

Also note that I've moved your proposal to http://dev.xwiki.org/xwiki/bin/view/Drafts/L10N+Conventions since you had put it in the documentation place for established practices while it's only a proposal ATM and it goes against an existing voted rule.

Thanks a lot for working on this.

Thanks
-Vincent

On Nov 24, 2012, at 3:55 AM, Sergiu Dumitriu <[hidden email]> wrote:

> Hi devs,
>
> I've written some conventions for translation messages at
> http://dev.xwiki.org/xwiki/bin/view/Community/L10N+Conventions
>
> Please provide feedback, since we terribly lack some proper rules here,
> and there aren't two applications that use the same conventions. Now
> that we have support for modular translation documents, it's a good time
> to clean up translations and move things out of ApplicationProperties
> into each application.
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] L10N Conventions

Sergiu Dumitriu-3
On 11/27/2012 05:32 AM, Vincent Massol wrote:
> Hi Sergiu,
>
> Good initiative! I've now taken the time to read your proposal. Some comments:
>
> * Regarding the change of key format, I believe this requires a separate VOTE  email since the previous format was already voted (and the result is documented at http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#HTranslationPropertyNaming ).

I agree. I was pretty certain that there is a standard, but couldn't
find it in there. My bad, I should have looked more thoroughly.

I didn't remember the previous vote, and it didn't get that much
attention as far as I can see. Do we have a rule that says that once a
VOTE is passed, it is not possible to re-vote on the subject and we'll
have to live forever with the results of a vote?

I'll re-send as a vote once we all agree with the rules. This proposal
was more to get the discussion started about what the conventions should
be. I worked several hours on the initial document, but it's still not
exhaustive, and it will require a few more hours to get it to a workable
state.

> The VOTE would also needs to mention what we do for existing keys and how do we ensure the new format would be used properly (it's quite complex).
>
> I also believe we should maybe not put the top level module as prefix since we now have a single product which is platform/XE and having this prefix makes the key more brittle. For the same reason that we don't use "platform" as a prefix in the
package name for java classes.

I agree, and this will also solve the current problem that we have when
moving modules from XE to platform. But this is an incompatible change,
even with the current rules, and will definitely require a vote.

And actually it has been used already in several places, like
activitystream, watchlist, panels, admin... Like I said, whatever rule
we pick, there will be more translations that won't abide to it; there's
no clear majority in that mess.

> In your VOTE email also explain more in detail when to use camel case vs a dot. For example:  error.invalidFormat vs error.format.invalid.

OK, I'll do that, but it's a wiki, anyone should feel free to add his
opinions in there.

>
> * The rest seems ok to me with good practices
>
> * One note: we already have some rules regarding deprecations, see http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#HTranslationPropertyDeprecations
>
> * Your proposal is missing a section about deciding when to use translations keys and when to use translated documents.

I started that at the end of the "Rules for translating composite and
long messages" section, and I was planning to add exactly this
information: when to use a translation key, and when to translate the
whole document. But it was really late and I didn't have a clear rule in
mind, so I left that for later.

> For example if I have a page like this:
>
> "
> <2 sentences here>
>
> {{velocity}}
> #if ($hasAdmin)
>   // do something here
> #end
> {{/velocity}}
>
> <some other sentence>
> "
>
> Should it be using translations keys or translation documents with possibly a refactoring to move the velocity code in another document, resulting in minimal macro usage:
>
> "
> <2 sentences here>
>
> {{include reference="document containing the code"/}}
>
> <some other sentence>
> "
>
> ?
>
> Also note that I've moved your proposal to http://dev.xwiki.org/xwiki/bin/view/Drafts/L10N+Conventions since you had put it in the documentation place for established practices while it's only a proposal ATM and it goes against an existing voted rule.
>
> Thanks a lot for working on this.
>
> Thanks
> -Vincent
>
> On Nov 24, 2012, at 3:55 AM, Sergiu Dumitriu <[hidden email]> wrote:
>
>> Hi devs,
>>
>> I've written some conventions for translation messages at
>> http://dev.xwiki.org/xwiki/bin/view/Community/L10N+Conventions
>>
>> Please provide feedback, since we terribly lack some proper rules here,
>> and there aren't two applications that use the same conventions. Now
>> that we have support for modular translation documents, it's a good time
>> to clean up translations and move things out of ApplicationProperties
>> into each application.


--
Sergiu Dumitriu
http://purl.org/net/sergiu
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] L10N Conventions

vmassol
Administrator

On Nov 28, 2012, at 12:33 AM, Sergiu Dumitriu <[hidden email]> wrote:

> On 11/27/2012 05:32 AM, Vincent Massol wrote:
>> Hi Sergiu,
>>
>> Good initiative! I've now taken the time to read your proposal. Some comments:
>>
>> * Regarding the change of key format, I believe this requires a separate VOTE  email since the previous format was already voted (and the result is documented at http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#HTranslationPropertyNaming ).
>
> I agree. I was pretty certain that there is a standard, but couldn't
> find it in there. My bad, I should have looked more thoroughly.
>
> I didn't remember the previous vote, and it didn't get that much
> attention as far as I can see. Do we have a rule that says that once a
> VOTE is passed, it is not possible to re-vote on the subject and we'll
> have to live forever with the results of a vote?

Anyone can send a VOTE about anything at any time. Of course, it doesn't mean it'll get accepted even if the new VOTE is better because we have to take into account backward compatibility and the cost of migrating from the old way to the new proposed way which could be costly.

> I'll re-send as a vote once we all agree with the rules. This proposal
> was more to get the discussion started about what the conventions should
> be. I worked several hours on the initial document, but it's still not
> exhaustive, and it will require a few more hours to get it to a workable
> state.

Ok, so in the meantime it means Thomas D. and whoever write translations will need to continue using the current agreed practice of using <top level module>.<module>.<camelcasekey> and they'll have to migrate later on if the VOTE is passed.

Thanks
-Vincent

>> The VOTE would also needs to mention what we do for existing keys and how do we ensure the new format would be used properly (it's quite complex).
>>
>> I also believe we should maybe not put the top level module as prefix since we now have a single product which is platform/XE and having this prefix makes the key more brittle. For the same reason that we don't use "platform" as a prefix in the
> package name for java classes.
>
> I agree, and this will also solve the current problem that we have when
> moving modules from XE to platform. But this is an incompatible change,
> even with the current rules, and will definitely require a vote.
>
> And actually it has been used already in several places, like
> activitystream, watchlist, panels, admin... Like I said, whatever rule
> we pick, there will be more translations that won't abide to it; there's
> no clear majority in that mess.
>
>> In your VOTE email also explain more in detail when to use camel case vs a dot. For example:  error.invalidFormat vs error.format.invalid.
>
> OK, I'll do that, but it's a wiki, anyone should feel free to add his
> opinions in there.
>
>>
>> * The rest seems ok to me with good practices
>>
>> * One note: we already have some rules regarding deprecations, see http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#HTranslationPropertyDeprecations
>>
>> * Your proposal is missing a section about deciding when to use translations keys and when to use translated documents.
>
> I started that at the end of the "Rules for translating composite and
> long messages" section, and I was planning to add exactly this
> information: when to use a translation key, and when to translate the
> whole document. But it was really late and I didn't have a clear rule in
> mind, so I left that for later.
>
>> For example if I have a page like this:
>>
>> "
>> <2 sentences here>
>>
>> {{velocity}}
>> #if ($hasAdmin)
>>  // do something here
>> #end
>> {{/velocity}}
>>
>> <some other sentence>
>> "
>>
>> Should it be using translations keys or translation documents with possibly a refactoring to move the velocity code in another document, resulting in minimal macro usage:
>>
>> "
>> <2 sentences here>
>>
>> {{include reference="document containing the code"/}}
>>
>> <some other sentence>
>> "
>>
>> ?
>>
>> Also note that I've moved your proposal to http://dev.xwiki.org/xwiki/bin/view/Drafts/L10N+Conventions since you had put it in the documentation place for established practices while it's only a proposal ATM and it goes against an existing voted rule.
>>
>> Thanks a lot for working on this.
>>
>> Thanks
>> -Vincent
>>
>> On Nov 24, 2012, at 3:55 AM, Sergiu Dumitriu <[hidden email]> wrote:
>>
>>> Hi devs,
>>>
>>> I've written some conventions for translation messages at
>>> http://dev.xwiki.org/xwiki/bin/view/Community/L10N+Conventions
>>>
>>> Please provide feedback, since we terribly lack some proper rules here,
>>> and there aren't two applications that use the same conventions. Now
>>> that we have support for modular translation documents, it's a good time
>>> to clean up translations and move things out of ApplicationProperties
>>> into each application.
>

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