28 Nov
2012
28 Nov
'12
12:33 a.m.
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#HTransla…
).
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#HTransla…
* 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 <sergiu(a)xwiki.org> 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