+1 for the proposed changes. For me it's easier to scan and understand where the key is used if the parts (modules, sections) are separated by a dot, rather than using only camel case.
Thanks, Marius On Fri, Feb 20, 2015 at 5:29 PM, [email protected] <[email protected]> wrote: > 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#HTranslationPropertyNaming > > 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 > > 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#HTranslationPropertyDeprecations > 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 > > > > > > > > > > > > _______________________________________________ > devs mailing list > [email protected] > http://lists.xwiki.org/mailman/listinfo/devs _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
