23 Feb
2015
23 Feb
'15
1:40 p.m.
+1 for having a standard.
I had no problem with the current standard. In the end it is just an ID,
not an API.
What is more important to me is ID collisions. We have the habit of using
translation documents with 'Wiki' scope pretty much everywhere. Maybe it
would be smarter to see translation objects/documents like SSX or JSX
objects that are generally used 'On Demand', more importantly now that we
want to drop the prefix (something which I like, but also see potential
problems with). Of course, we can not do anything about java translations
(ApplicationResources.properties). In any case, I think we are just asking
for it when it comes to translation key collisions and we are bound to see
problems in the future, unless we start taking it into consideration
(solutions, tools to debug translation problems, etc.). An example that
comes to my mind is that we have 2 forum applications in e.x.o *and* a
bulletin board application (which is basically a 3rd forum app).
I`m +1 for the proposed changes (specially since people seem to like dots
in their translation keys and because of the ease of moving code around,
introduced by the removal of the product).
Thanks,
Eduard
On Mon, Feb 23, 2015 at 11:46 AM, vincent(a)massol.net <vincent(a)massol.net>
wrote:
On 23 Feb 2015 at 10:32:47, Guillaume Louis-Marie Delhumeau (
gdelhumeau@xwiki.com(mailto:gdelhumeau@xwiki.com)) wrote:
Simply that it was not following our naming rule, see
http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#HTransla…
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
2015-02-20 16:29 GMT+01:00 vincent(a)massol.net :
> Hi devs,
>
> At the moment the VOTED rule for naming our translation properties is
the
> one defined at
>
>
http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#HTransla…
>
> Back in 2012 Sergiu started drafting an extended "L10N Conventions”
> document for best practices around writing translation properties at
> http://dev.xwiki.org/xwiki/bin/view/Drafts/L10N+Conventions
>
> Sergiu sent this a proposal in this mail thread:
> http://markmail.org/message/ofl23yorvxsqhn4x
>
> When Sergiu did this he didn’t realize we already had a VOTED rule for
> naming our translation properties and his proposal was in conflit with
> that. However, in this mail thread, several developers mentioned that
even
> though they votes the previous naming rules
they didn’t fully like it
and
> preferred the one Sergiu was proposing.
Several suggestion for
improvements
> were also proposed. It was suggested in that
thread (and Sergiu agreed)
> that he should resend a VOTE to change those established rules.
Apparently
> he didn’t get the time/will to do it since I
couldn’t find such a mail.
>
> In addition several developers are apparently not following the current
> rules (BAD! :)). For example in the xwiki-platform-icon-ui module, the
> Translations.xml page has the following which is NOT following the
current
rules:
platform.icon.picker.preview=Preview with:
platform.icon.picker.loading=Loading
What is wrong with that? Dots are not allowed in the property name?
picker.preview should have been called pickerPreview? What if the
property
name is long, such as
platform.wiki.users.join.request.cancelYes? It
should
have been
platform.wiki.usersJoinRequestCancelYes?
yes, something like (which I agree is not that nice - it works better for
config properties than for translating UI elements):
platform.wiki.yesLabelCancelUserJoinRequest or
platform.wiki.cancelUserJoinRequestYesLabel
Now this new VOTE goes in your direction but the point is that it’s hard
to have common naming rules so even if someone doesn’t like the new
proposal, when it’s voted we should all try to follow it (or raise it if
there are issues).
Thanks
-Vincent
> And most translation keys found in contrib
apps at
> http://l10n.xwiki.org/xwiki/bin/view/Contrib/WebHome are also not
> following these rules (although we don’t enforce anything for contrib
> projects, when they are coded by devs from the XWiki dev team or by
known
> contributors, it would be a good thing to
follow the same rule,
especially
> as, in the future, we want to provide a path
to move from contrib
sandbox
> to contrib extensions). For example I see
the following type of naming:
> “polls.vote.instructions.single”.
>
> Thus, with this email I’d like to try agreeing on a new naming format
and
> conventions.
>
> I propose to VOTE for making
> http://dev.xwiki.org/xwiki/bin/view/Drafts/L10N+Conventions our
official
> practice with the following change for the
property naming part:
>
> "
> Keys should have the following format:
> ##[module]*[.section]*.element[.part]*##, where:
>
> * ##module## is the name of the module or application being translated,
> like ##blog##, ##faq##, ##statistics##… Since a module can have
submodules,
> there can be several module names. For
example the SOLR Search UI is
> located in
> ##xwiki-platform-search/xwiki-platform-solr/xwiki-platform-solr-ui##
and
> would have keys starting with
##search.solr.##.
> * zero, one or more ##section## parts that further refine the location
of
> the string being translated; for example, a
key starting with
> ##theme.colors.wizard.## refers to a text located in the //wizard//
for the
> //color// part of the //theme// application
(currently there are only
color
> themes, but in the future we might add icon
themes, layout themes, and
so
> on), ##macro.python.parameter.## refers to
//parameters// of the
//python//
> //macro//, while a key starting with
##userdirectory.## belongs to the
main
> and only section of the //user directory//
application
> * ##element## identifies the main element being translated, but such an
> element could have several related parts.
> * ##part## identifies a text related to a main element, such as the
> ##label## that describes an input, the ##placeholder## found inside
that
> input, the ##tooltip## that appears when
hovering that input, the
##hint##
> that is displayed before the field and
provides additional details
about
> what it, the ##error.empty## or
##error.invalidFormat## displayed when
> there are validation errors, and so on
>
> Individual parts of the key should use **camelCase** if more than one
word
> is needed to identify the element.
> “
>
> Note that I’ve removed the ##product## part from Sergiu’s proposal (the
> reasoning is here: http://markmail.org/message/ocijlegslw45yedu). In
> short this makes it simpler to move apps around without breaking the
> translation keys. Of course it reduces the namespace and increases
> likelihood of translation clashes with user-provided extensions but I
don’t
> think it’s going to be a problem and
user-provided extensions should
have a
> unique app name anyway.
>
> I would also point to
>
http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#HTransla…
for
> the deprecation part.
>
> The big question is what to do with existing translations and the only
> answer I have so far is:
> * Use the new rules when adding new translation keys (after, and if,
it’s
voted)
* Don’t touch existing keys for now (since that would loose all
translations) but implement the following first, and once it’s done,
refactor existing translations over time:
** Add support for a deprecation section in Translations.xml’s content,
honoured by l10n in the same way that we do it for
ApplicationResources.properties
** Add the new key
** Move the old key to the deprecation section
(in ApplicationResources.properties or in Translations.xml)
** Make the old key point to the new key, using a special syntax. For
example: my.old.deprecated.key = @{new.shiny.key}
Here’s my +1
Thanks
-Vincent