28 Nov
2012
28 Nov
'12
9:07 a.m.
On Nov 28, 2012, at 12:33 AM, Sergiu Dumitriu <sergiu(a)xwiki.org> wrote:
On 11/27/2012 05:32 AM, Vincent Massol wrote:
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.
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.
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#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.