Skip to content

Commit

Permalink
README: Switch to triple back-ping for code blocks and improve syntax…
Browse files Browse the repository at this point in the history 
… highlighting
  • Loading branch information
@Munter
Munter committed Dec 31, 2014
1 parent d9acf3d commit 072557a
Showing 1 changed file with 115 additions and 75 deletions.
190 changes: 115 additions & 75 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -87,25 +87,33 @@ Optional first step: To take full advantage of the image processing
and optimization features, you need several libraries and command line
utilities installed. On Ubuntu you can grab them all by running:

sudo apt-get install -y libcairo2-dev libjpeg8-dev libgif-dev optipng pngcrush pngquant libpango1.0-dev graphicsmagick libjpeg-progs inkscape
```
sudo apt-get install -y libcairo2-dev libjpeg8-dev libgif-dev optipng pngcrush pngquant libpango1.0-dev graphicsmagick libjpeg-progs inkscape
```

Or on OS X, with [homebrew](http://brew.sh/):

brew install cairo jpeg giflib optipng pngcrush pngquant pango graphicsmagick jpeg-turbo inkscape
export PKG_CONFIG_PATH=/opt/X11/lib/pkgconfig
```
brew install cairo jpeg giflib optipng pngcrush pngquant pango graphicsmagick jpeg-turbo inkscape
export PKG_CONFIG_PATH=/opt/X11/lib/pkgconfig
```


Then make sure you have node.js and <a href="http://npmjs.org/">npm</a> installed,
then run:

$ npm install -g assetgraph-builder
```
$ npm install -g assetgraph-builder
```

Now you'll have the `buildProduction` script in your PATH.

Usage
-----

$ buildProduction --outroot outputPath [--root webrootPath] [startingAssets]
```
$ buildProduction --outroot outputPath [--root webrootPath] [startingAssets]
```

Assetgraph needs a web root to resolve URLs correctly. If you pass in the `--root` option assetgraph will use it, otherwise it will take a best guess based on your `startingAssets`.

Expand All @@ -120,17 +128,21 @@ Example usage

Build a single page application:

buildProduction --outroot path/to/production --root path/to/dev path/to/dev/index.html
```
buildProduction --outroot path/to/production --root path/to/dev path/to/dev/index.html
```

This will load path/to/dev/index.html, follow all local relations to
JavaScript, CSS, etc., perform the above mentioned optimizations, then
output the result to the directory `path/to/production`.

Create a CDN-enabled build:

buildProduction --outroot path/to/production --root path/to/dev path/to/dev/index.html \
--cdnroot http://xxxxxx.cloudfront.net/static/cdn \
--cdnoutroot path/to/production/static/cdn
```
buildProduction --outroot path/to/production --root path/to/dev path/to/dev/index.html \
--cdnroot http://xxxxxx.cloudfront.net/static/cdn \
--cdnoutroot path/to/production/static/cdn
```

This will produce a build that assumes that the contents of `path/to/production/static/cdn`
are available at `http://xxxxxx.cloudfront.net/static/cdn`. We recommend putting the entire
Expand Down Expand Up @@ -334,28 +346,30 @@ example `--locales en_us,da,fr,de`.
The translations themselves reside in separate JSON files with an
`i18n` extension. Example syntax (`foo.i18n`):

{
"myKeyName": {
"en": "The value in English",
"da": "Værdien på dansk"
},
"myOtherKeyName": {
"en": "The other value in English",
"da": "Den anden værdi på dansk"
},
"advancedKeyWithPlaceholders": {
"en": "Showing {0}-{1} of {2} records",
"da": "Der er {2} i alt, viser fra nr. {0} til nr. {1}"
},
"IAmSoXToday": {
"en": "I am so {0} today",
"da": "Jeg er så {0} i dag"
},
"TheColor": {
"en": "blue",
"da": "blå"
}
```json
{
"myKeyName": {
"en": "The value in English",
"da": "Værdien på dansk"
},
"myOtherKeyName": {
"en": "The other value in English",
"da": "Den anden værdi på dansk"
},
"advancedKeyWithPlaceholders": {
"en": "Showing {0}-{1} of {2} records",
"da": "Der er {2} i alt, viser fra nr. {0} til nr. {1}"
},
"IAmSoXToday": {
"en": "I am so {0} today",
"da": "Jeg er så {0} i dag"
},
"TheColor": {
"en": "blue",
"da": "blå"
}
}
```

### JavaScript i18n syntax ###

Expand All @@ -376,36 +390,42 @@ actually have something to put in them.

JavaScript example:

INCLUDE('foo.i18n');
```javascript
INCLUDE('foo.i18n');

// This alerts "The value in English" or "Værdien på dansk" depending on which build you're running:
alert(TR('myKeyName', 'the default value'));
// This alerts "The value in English" or "Værdien på dansk" depending on which build you're running:
alert(TR('myKeyName', 'the default value'));

// This alerts "Showing 1-50 of 100 records" or "Der er 100 i alt, viser fra nr. 1 til nr. 50":
var foo = 1, bar = 50;
alert(TRPAT('advancedKeyWithPlaceholders', 'the default value')(foo, bar, 100));
// This alerts "Showing 1-50 of 100 records" or "Der er 100 i alt, viser fra nr. 1 til nr. 50":
var foo = 1, bar = 50;
alert(TRPAT('advancedKeyWithPlaceholders', 'the default value')(foo, bar, 100));

var myRenderer = TRPAT('advancedKeyWithPlaceholders', 'the default value');
// This also alerts "Showing 1-2 of 3 records" or "Der er 100 i alt, viser fra nr. 1 til nr. 50":
alert(myRenderer(1, 50, 100));
var myRenderer = TRPAT('advancedKeyWithPlaceholders', 'the default value');
// This also alerts "Showing 1-2 of 3 records" or "Der er 100 i alt, viser fra nr. 1 til nr. 50":
alert(myRenderer(1, 50, 100));
```

In production this compiles into (English version):

alert('The value in English');
var foo = 1, bar = 50;
alert('Showing ' + foo + '-' + bar + ' of 100 records');
```javascript
alert('The value in English');
var foo = 1, bar = 50;
alert('Showing ' + foo + '-' + bar + ' of 100 records');

var myRenderer = function (a0, a1, a2) {return 'Showing ' + a0 + '-' + a1 + ' of ' + a2 + ' records'};
alert(myRenderer(1, 50, 100));
var myRenderer = function (a0, a1, a2) {return 'Showing ' + a0 + '-' + a1 + ' of ' + a2 + ' records'};
alert(myRenderer(1, 50, 100));
```

And the Danish version:

alert('Værdien på dansk');
var foo = 1, bar = 50;
alert('Der er 100 i alt, viser fra nr. ' + foo + ' til nr. ' + bar);
```javascript
alert('Værdien på dansk');
var foo = 1, bar = 50;
alert('Der er 100 i alt, viser fra nr. ' + foo + ' til nr. ' + bar);

var myRenderer = function (a0, a1, a2) {return 'Der er ' + a3 + ' i alt, viser nr. ' + a0 + ' til nr. ' + a1;};
alert(myRenderer(1, 50, 100));
var myRenderer = function (a0, a1, a2) {return 'Der er ' + a3 + ' i alt, viser nr. ' + a0 + ' til nr. ' + a1;};
alert(myRenderer(1, 50, 100));
```

As the translation files consist of plain JSON, translated values do
not have to be strings. This enables more advanced features, that you
Expand All @@ -416,30 +436,34 @@ real name. That could be achieved the following way.

The translation file:

{
"FolderName": {
"en": {
"Inbox" : "Inbox",
"Draft" : "Draft",
"Sent" : "Sent Mail"
},
"da": {
"Inbox" : "Indbakke",
"Draft" : "Kladder",
"Trash" : "Sendte e-mails"
}
```json
{
"FolderName": {
"en": {
"Inbox" : "Inbox",
"Draft" : "Draft",
"Sent" : "Sent Mail"
},
"da": {
"Inbox" : "Indbakke",
"Draft" : "Kladder",
"Trash" : "Sendte e-mails"
}
}
}
```

The code translating the e-mail folder names:

var folderTranslations = TR("FolderName", {
"Inbox" : "Inbox",
"Draft" : "Draft",
"Sent" : "Sent Mail"
});
```javascript
var folderTranslations = TR("FolderName", {
"Inbox" : "Inbox",
"Draft" : "Draft",
"Sent" : "Sent Mail"
});

return folderTranslations[folderName] || folderName;
return folderTranslations[folderName] || folderName;
```

The `TR` function call extracts the internationalized `FolderName`
structure or uses the provided default. Then we look for the folder
Expand All @@ -450,37 +474,53 @@ otherwise we just return the folder name.

Simple example:

<p><span data-i18n="myKeyName">The default text</span></p>
```html
<p><span data-i18n="myKeyName">The default text</span></p>
```

Span tags that only have a `data-i18n` attribute are removed, so the above compiles to:

<p>The value in English</p>
```html
<p>The value in English</p>
```

If you put the `data-i18n` attribute on a different tag (eg. `<div>`
or `<h2>`) or use a span with additional attributes, the tag itself
will be preserved, and only the `data-i18n` attribute will be removed:

<span class="foo" data-i18n="myKeyName">The default text</span>
```html
<span class="foo" data-i18n="myKeyName">The default text</span>
```

Which compiles into:

<span class="foo">The value in English</span>
```html
<span class="foo">The value in English</span>
```

Non-text node elements inside the default text are interpreted as placeholders numbered from left to right:

<span data-i18n="advancedKeyWithPlaceholders">Showing <span>1</span> to <span>50</span> of <span>100</span></span>
```html
<span data-i18n="advancedKeyWithPlaceholders">Showing <span>1</span> to <span>50</span> of <span>100</span></span>
```

In the Danish version the above compiles to:

Der er <span>100</span> i alt, viser nr. <span>1</span> til nr. <span>50</span>.
```html
Der er <span>100</span> i alt, viser nr. <span>1</span> til nr. <span>50</span>.
```

For HTML attributes there's a more elaborate, Knockout.js-ish syntax for the `data-i18n` attribute:

<div title="The default value" data-i18n="text: 'myKeyName', attr: {title: 'myOtherKeyName'}">The default value</span>
```html
<div title="The default value" data-i18n="text: 'myKeyName', attr: {title: 'myOtherKeyName'}">The default value</span>
```

Which compiles to this in English:

<div title="The other value in English">The value in English</span>
```html
<div title="The other value in English">The value in English</span>
```


### I18n of HTML chunks in JavaScript ###
Expand Down

0 comments on commit 072557a

Please sign in to comment.