Opened 8 years ago

Closed 8 years ago

#13721 closed enhancement (invalid)

Documentation for the build system re: localizing dijits

Reported by: Nick Fenwick Owned by:
Priority: high Milestone: tbd
Component: Documentation Version: 1.6.1
Keywords: localization, build, docs Cc:
Blocked By: Blocking:

Description

I've written a page of documentation that I would like to submit for inclusion in the 'build' set of pages.

http://docs.dojocampus.org/build/localizationExample

It's actually 80% about how to structure the files on disk and how to use the resultant build in production, and only about 20% about the build process, but I felt that most users asking the question "how do I provide localised string bundles for my dijits and build them into one single strings bundle and use it in production" would come first to the 'build' section of the docs.

I don't feel that any current page really addresses this question or answers it in the detail I've attempted to provide.

I figured it out by looking at how ValidationTextBox? uses its invalidMessage et. al. strings, and generally reverse engineering things. If there's a better way to pull in a strings bundle, I'd love to hear it.

The page could be enhanced with:

  • mention of xd builds and how to link to built layers hosted on servers remote to the source dojo library (see the ArcGIS/ESRI comment at the bottom)
  • mention of a base dijit to handle localisations for all custom dijits (someone posted on the mailing list to say this is an approach they use).

Can someone review this and include it in the flow of build docs? I don't know how to include it in the proper flow of reference documentation.

Change History (4)

comment:1 Changed 8 years ago by PEM

Great Doc ! Love it ! It has a nice down to earth approach and is clear ! I'm pretty sure it will help a lot of people, we see questions about builds quite frequently on irc and mailing list.

comment:2 Changed 8 years ago by Nick Fenwick

Thanks PEM.

By the way, just to clarify my ignorance on some issues that should really be at least mentioned in my document:

I've no idea why the ValidationTextBox? string resource file looks like it does.

define({ root:

begin v1.x content ({

test: 'this is a test'

}) end v1.x content })

What is 'define'? Why 'root'? Is the comment significant? The ValidationTextBox? file also has extra stuff, dijit/form/nls/validate.js contains:

define({ root: begin v1.x content ({

invalidMessage: "The value entered is not valid.", missingMessage: "This value is required.", rangeMessage: "This value is out of range."

}) end v1.x content , "zh": true, "zh-tw": true, "tr": true, "th": true, "sv": true, "sl": true, "sk": true, "ru": true, "ro": true, "pt": true, "pt-pt": true, "pl": true, "nl": true, "nb": true, "ko": true, "kk": true, "ja": true, "it": true, "hu": true, "he": true, "fr": true, "fi": true, "es": true, "el": true, "de": true, "da": true, "cs": true, "ca": true, "ar": true });

I don't know what all those locales are doing there or what difference they make to the build process.

I've just amended the docs page to include some links to other existing docs pages, and a 'trees of locales' section to try to clarify how sub-locales relate to each other.

comment:3 Changed 8 years ago by ben hockey

by default, everything in the wiki is included as part of the docs. so nothing special needs to happen there. also, your style seems appropriate and easy enough to read. i got a little bit lost but i was rushing through it.

however, from reading your guide it seems your advice might not be accurate. defining alternative locales is much simpler than you seem to have made it (maybe i'm misunderstanding your approach) and you should be able to use the same html page with source or build (ie you shouldn't need to include a script tag for your built layer) if you change your approach to have a testdijits.js file in your source that has the dojo.requires for all your widgets and then dojo.require that in your html file. this also simplifies your build profile so that the testdijits.js layer has only that one dependency. see http://requirejs.org/docs/api.html#i18n for an explanation of how to write your nls packages so that alternative locales can be found. from that page:

//Contents of my/nls/colors.js
define({
    "root": {
        "red": "red",
        "blue": "blue",
        "green": "green"
    },
    "fr-fr": true
});

//Contents of my/nls/fr-fr/colors.js
define({
    "red": "rouge",
    "blue": "bleu",
    "green": "vert"
});

also, some of your advice is going to be invalid once 1.7 is released. particularly, it seems you may be tinkering with the build output to make this work and that's not going to be the same in 1.7. maybe i'm misunderstanding because i'm not sure where this line in particular is added - it seems you're saying to add it in the build output?

dojo.requireLocalization("testdijits", "Foo", null, "ROOT,fr");

anyhow, i expect rawld will have docs for the new build system to help understand how it works.

comment:4 Changed 8 years ago by ben hockey

Resolution: invalid
Status: newclosed

i'm closing this since this is not really the place to discuss docs though - unless there are bugs in the documentation or the doc tools.

i'd say take it to the mailing list for discussion.

Note: See TracTickets for help on using tickets.