| 1 | locale
|
| 2 | ======
|
| 3 |
|
| 4 | [](http://travis-ci.org/jed/locale)
|
| 5 |
|
| 6 | locale is a [node.js][node] module for negotiating HTTP locales for incoming browser requests. It can be used as a standalone module for HTTP or as [Express][express]/[Connect][connect] middleware.
|
| 7 |
|
| 8 | Examples
|
| 9 | --------
|
| 10 |
|
| 11 | ### For the node.js HTTP module
|
| 12 | ```javascript
|
| 13 | var http = require("http")
|
| 14 | , locale = require("locale")
|
| 15 | , supported = new locale.Locales(["en", "en_US", "ja"])
|
| 16 |
|
| 17 | http.createServer(function(req, res) {
|
| 18 | var locales = new locale.Locales(req.headers["accept-language"])
|
| 19 | res.writeHeader(200, {"Content-Type": "text/plain"})
|
| 20 | res.end(
|
| 21 | "You asked for: " + req.headers["accept-language"] + "\n" +
|
| 22 | "We support: " + supported + "\n" +
|
| 23 | "Our default is: " + locale.Locale["default"] + "\n" +
|
| 24 | "The best match is: " + locales.best(supported) + "\n"
|
| 25 | )
|
| 26 | }).listen(8000)
|
| 27 | ```
|
| 28 |
|
| 29 | ### For Connect/Express
|
| 30 | ```javascript
|
| 31 | var http = require("http")
|
| 32 | , express = require("express")
|
| 33 | , locale = require("locale")
|
| 34 | , supported = ["en", "en_US", "ja"]
|
| 35 | , app = express.createServer(locale(supported))
|
| 36 |
|
| 37 | app.get("/", function(req, res) {
|
| 38 | res.header("Content-Type", "text/plain")
|
| 39 | res.send(
|
| 40 | "You asked for: " + req.headers["accept-language"] + "\n" +
|
| 41 | "We support: " + supported + "\n" +
|
| 42 | "Our default is: " + locale.Locale["default"] + "\n" +
|
| 43 | "The best match is: " + req.locale + "\n"
|
| 44 | )
|
| 45 | })
|
| 46 |
|
| 47 | app.listen(8000)
|
| 48 | ```
|
| 49 |
|
| 50 | Install
|
| 51 | -------
|
| 52 |
|
| 53 | $ npm install locale
|
| 54 |
|
| 55 | API
|
| 56 | ---
|
| 57 |
|
| 58 | ### locale(supportedLocales)
|
| 59 |
|
| 60 | This module exports a function that can be used as Express/Connect middleware. It takes one argument, a list of supported locales, and adds a `locale` property to incoming HTTP requests, reflecting the most appropriate locale determined using the `best` method described below.
|
| 61 |
|
| 62 | ### new locale.Locale(languageTag)
|
| 63 |
|
| 64 | The Locale constructor takes a [language tag][langtag] string consisting of an ISO-639 language abbreviation and optional two-letter ISO-3166 country code, and returns an object with a `language` property containing the former and a `country` property containing the latter.
|
| 65 |
|
| 66 | ### locale.Locale["default"]
|
| 67 |
|
| 68 | The default locale for the environment, as parsed from `process.env.LANG`. This is used as the fallback when the best language is calculated from the intersection of requested and supported locales.
|
| 69 |
|
| 70 | ### locales = new locale.Locales(acceptLanguageHeader)
|
| 71 |
|
| 72 | The Locales constructor takes a string compliant with the [`Accept-Language` HTTP header][header], and returns a list of acceptible locales, optionally sorted in descending order by quality score.
|
| 73 |
|
| 74 | ### locales.best([supportedLocales])
|
| 75 |
|
| 76 | This method takes the target locale and compares it against the optionally provided list of supported locales, and returns the most appropriate locale based on the quality scores of the target locale. If no match exists, the default locale is returned.
|
| 77 |
|
| 78 | Copyright
|
| 79 | ---------
|
| 80 |
|
| 81 | Copyright (c) 2012 Jed Schmidt. See LICENSE.txt for details.
|
| 82 |
|
| 83 | Send any questions or comments [here](http://twitter.com/jedschmidt).
|
| 84 |
|
| 85 | [node]: http://nodejs.org
|
| 86 | [express]: http://expressjs.com
|
| 87 | [connect]: http://senchalabs.github.com/connect/
|
| 88 | [langtag]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.10
|
| 89 | [header]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.4 |
| \ | No newline at end of file |