improved i18n

README.md

@@ -36,8 +36,12 @@ Jekyll comes built-in with GitHub Pages. Since we are already using GitHub Pages
 
 Follow these steps:
 
-1. Create a directory for the language of your choice using its [ISO 639-1 code](http://en.wikipedia.org/wiki/ISO_639-1) as its name.
-2. Copy `index.md`, `api.md`, `starter/`, `guide/`, `api/`, `advanced/`, and `resources/` to the language directory.
-3. Update the `lang` variable in the markdown files in the copied file to the language you have selected.
-4. Create the header and footer HTML files for the language in the `_includes/` directory.
-5. Copy the `_includes/api/en` to the language of your choice.
+1. Create a directory for the language of your choice using its [ISO 639-1 code](http://www.loc.gov/standards/iso639-2/php/code_list.php) as its name.
+2. Copy `index.md`, `api.md`, `starter/`, `guide/`, `advanced/`, `resources/`, `4x/`, and `3x/`, to the language directory.
+3. Remove the link to 2.x docs from the "API Reference" menu.
+4. Update the `lang` variable in the copied markdown files.
+5. Update the `title` variable in the copied markdown files.
+6. Create the header and footer HTML files for the language in the `_includes/` directory, and make necessary edits to the contents.
+7. Create a copy of the `_includes/api/en` and rename it acording to the language code.
+8. Make sure to append `/\{\{ page.lang }}` to all the links within the site.
+

_includes/api/ru/3x/app-VERB.md

@@ -0,0 +1,57 @@
+<h3 id='app.VERB'>app.VERB(path, [callback...], callback)</h3>
+
+The `app.VERB()` methods provide the routing functionality
+in Express, where <strong>VERB</strong> is one of the HTTP verbs, such
+as `app.post()`. Multiple callbacks may be given, all are treated
+equally, and behave just like middleware, with the one exception that
+these callbacks may invoke `next('route')` to bypass the
+remaining route callback(s). This mechanism can be used to perform pre-conditions
+on a route then pass control to subsequent routes when there is no reason to proceed
+with the route matched.
+
+The following snippet illustrates the most simple route definition possible. Express
+translates the path strings to regular expressions, used internally to match incoming requests.
+Query strings are <em>not</em> considered when peforming these matches, for example "GET /"
+would match the following route, as would "GET /?name=tobi".
+
+~~~js
+app.get('/', function(req, res){
+  res.send('hello world');
+});
+~~~
+
+Regular expressions may also be used, and can be useful
+if you have very specific restraints, for example the following
+would match "GET /commits/71dbb9c" as well as "GET /commits/71dbb9c..4c084f9".
+
+~~~js
+app.get(/^\/commits\/(\w+)(?:\.\.(\w+))?$/, function(req, res){
+  var from = req.params[0];
+  var to = req.params[1] || 'HEAD';
+  res.send('commit range ' + from + '..' + to);
+});
+~~~
+
+Several callbacks may also be passed, useful for re-using middleware
+that load resources, perform validations, etc.
+
+~~~js
+app.get('/user/:id', user.load, function(){
+  // ... 
+})
+~~~
+
+These callbacks may be passed within arrays as well, these arrays are
+simply flattened when passed:
+
+~~~js
+var middleware = [loadForum, loadThread];
+
+app.get('/forum/:fid/thread/:tid', middleware, function(){
+  // ...
+})
+
+app.post('/forum/:fid/thread/:tid', middleware, function(){
+  // ...
+})
+~~~

_includes/api/ru/3x/app-all.md

@@ -0,0 +1,32 @@
+<h3 id='app.all'>app.all(path, [callback...], callback)</h3>
+
+This method functions just like the `app.VERB()` methods,
+however it matches all HTTP verbs. 
+
+This method is extremely useful for
+mapping "global" logic for specific path prefixes or arbitrary matches.
+For example if you placed the following route at the top of all other
+route definitions, it would require that all routes from that point on
+would require authentication, and automatically load a user. Keep in mind
+that these callbacks do not have to act as end points, `loadUser`
+can perform a task, then `next()` to continue matching subsequent
+routes.
+
+~~~js
+  app.all('*', requireAuthentication, loadUser);
+~~~
+
+Or the equivalent:
+
+~~~js
+  app.all('*', requireAuthentication)
+  app.all('*', loadUser);
+~~~
+
+Another great example of this is white-listed "global" functionality. Here
+the example is much like before, however only restricting paths prefixed with
+"/api":
+
+~~~js
+  app.all('/api/*', requireAuthentication);
+~~~

_includes/api/ru/3x/app-configure.md

@@ -0,0 +1,40 @@
+<h3 id='app.configure'>app.configure([env], callback)</h3>
+
+Conditionally invoke `callback` when `env` matches `app.get('env')`,
+aka `process.env.NODE_ENV`. This method remains for legacy reasons, and is effectively
+an `if` statement as illustrated in the following snippets. These functions are <em>not</em>
+required in order to use `app.set()` and other configuration methods.
+
+~~~js
+// all environments
+app.configure(function(){
+  app.set('title', 'My Application');
+})
+
+// development only
+app.configure('development', function(){
+  app.set('db uri', 'localhost/dev');
+})
+
+// production only
+app.configure('production', function(){
+  app.set('db uri', 'n.n.n.n/prod');
+})
+~~~
+
+Is effectively sugar for:
+
+~~~js
+// all environments
+app.set('title', 'My Application');
+
+// development only
+if ('development' == app.get('env')) {
+  app.set('db uri', 'localhost/dev');
+}
+
+// production only
+if ('production' == app.get('env')) {
+  app.set('db uri', 'n.n.n.n/prod');
+}
+~~~

_includes/api/ru/3x/app-disable.md

@@ -0,0 +1,9 @@
+<h3 id='app.disable'>app.disable(name)</h3>
+
+Set setting `name` to `false`.
+
+~~~js
+app.disable('trust proxy');
+app.get('trust proxy');
+// => false
+~~~

_includes/api/ru/3x/app-disabled.md

@@ -0,0 +1,12 @@
+<h3 id='app.disabled'>app.disabled(name)</h3>
+
+Check if setting `name` is disabled.
+
+~~~js
+app.disabled('trust proxy');
+// => true
+
+app.enable('trust proxy');
+app.disabled('trust proxy');
+// => false
+~~~

_includes/api/ru/3x/app-enable.md

@@ -0,0 +1,9 @@
+<h3 id='app.enable'>app.enable(name)</h3>
+
+Set setting `name` to `true`.
+
+~~~js
+app.enable('trust proxy');
+app.get('trust proxy');
+// => true
+~~~

_includes/api/ru/3x/app-enabled.md

@@ -0,0 +1,12 @@
+<h3 id='app.enabled'>app.enabled(name)</h3>
+
+Check if setting `name` is enabled.
+
+~~~js
+app.enabled('trust proxy');
+// => false
+
+app.enable('trust proxy');
+app.enabled('trust proxy');
+// => true
+~~~

_includes/api/ru/3x/app-engine.md

@@ -0,0 +1,39 @@
+<h3 id='app.engine'>app.engine(ext, callback)</h3>
+
+Register the given template engine `callback` as `ext`
+
+By default will `require()` the engine based on the
+file extension. For example if you try to render
+a "foo.jade" file Express will invoke the following internally,
+and cache the `require()` on subsequent calls to increase
+performance.
+
+~~~js
+app.engine('jade', require('jade').__express);
+~~~
+
+For engines that do not provide `.__express` out of the box -
+or if you wish to "map" a different extension to the template engine
+you may use this method. For example mapping the EJS template engine to
+".html" files:
+
+~~~js
+app.engine('html', require('ejs').renderFile);
+~~~
+
+In this case EJS provides a `.renderFile()` method with
+the same signature that Express expects: `(path, options, callback)`,
+though note that it aliases this method as `ejs.__express` internally
+so if you're using ".ejs" extensions you dont need to do anything.
+
+Some template engines do not follow this convention, the
+<a href="https://github.com/visionmedia/consolidate.js">consolidate.js</a>
+library was created to map all of node's popular template
+engines to follow this convention, thus allowing them to
+work seemlessly within Express.
+
+~~~js
+var engines = require('consolidate');
+app.engine('haml', engines.haml);
+app.engine('html', engines.hogan);
+~~~

_includes/api/ru/3x/app-get.md

@@ -0,0 +1,12 @@
+<h3 id='app.get'>app.get(name)</h3>
+
+Get setting `name` value.
+
+~~~js
+app.get('title');
+// => undefined
+
+app.set('title', 'My Site');
+app.get('title');
+// => "My Site"
+~~~

_includes/api/ru/3x/app-listen.md

@@ -0,0 +1,36 @@
+<h3 id='app.listen'>app.listen()</h3>
+
+Bind and listen for connections on the given host and port,
+this method is identical to node's <a href="http://nodejs.org/api/http.html#http_server_listen_port_hostname_backlog_callback">http.Server#listen()</a>.
+
+~~~js
+var express = require('express');
+var app = express();
+app.listen(3000);
+~~~
+
+The `app` returned by `express()` is in fact a JavaScript
+`Function`, designed to be passed to node's http servers as a callback
+to handle requests. This allows you to provide both HTTP and HTTPS versions of
+your app with the same codebase easily, as the app does not inherit from these,
+it is simply a callback:
+
+~~~js
+var express = require('express');
+var https = require('https');
+var http = require('http');
+var app = express();
+
+http.createServer(app).listen(80);
+https.createServer(options, app).listen(443);
+~~~
+
+The `app.listen()` method is simply a convenience method defined as,
+if you wish to use HTTPS or provide both, use the technique above.
+
+~~~js
+app.listen = function(){
+  var server = http.createServer(this);
+  return server.listen.apply(server, arguments);
+};
+~~~

_includes/api/ru/3x/app-locals.md

@@ -0,0 +1,47 @@
+<h3 id='app.locals'>app.locals</h3>
+
+Application local variables are provided to all templates
+rendered within the application. This is useful for providing
+helper functions to templates, as well as app-level data.
+
+~~~js
+app.locals.title = 'My App';
+app.locals.strftime = require('strftime');
+~~~
+
+The `app.locals` object is a JavaScript `Function`,
+which when invoked with an object will merge properties into itself, providing
+a simple way to expose existing objects as local variables.
+
+~~~js
+app.locals({
+  title: 'My App',
+  phone: '1-250-858-9990',
+  email: '[email protected]'
+});
+
+app.locals.title
+// => 'My App'
+
+app.locals.email
+// => '[email protected]'
+~~~
+
+A consequence of the `app.locals` Object being ultimately a Javascript Function Object is that you must not reuse existing (native) named properties for your own variable names, such as `name, apply, bind, call, arguments, length, constructor`.
+
+~~~js
+app.locals({name: 'My App'});
+
+app.locals.name
+// => return 'app.locals' in place of 'My App' (app.locals is a Function !)
+// => if name's variable is used in a template, a ReferenceError will be returned.
+~~~
+
+The full list of native named properties can be found in many specifications. The <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference">JavaScript specification</a> introduced original properties, some of which still recognized by modern engines, and the <a href="http://www.ecma-international.org/ecma-262/5.1/">EcmaScript specification</a> then built on it and normalized the set of properties, adding new ones and removing deprecated ones. Check out properties for Functions and Objects if interested.
+
+By default Express exposes only a single app-level local variable, `settings`.
+
+~~~js
+app.set('title', 'My App');
+// use settings.title in a view
+~~~