+1 and same comment than Marius On Fri, Feb 27, 2015 at 11:22 AM, Marius Dumitru Florea <[email protected]> wrote: > +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
-- Thomas Mortagne _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
