1 [![GoDoc](https://godoc.org/github.com/johngb/langreg?status.svg)](https://godoc.org/github.com/johngb/langreg)
2 [![wercker status](https://app.wercker.com/status/6774907cc34f2b397f3b29e39948f799/s/master "wercker status")](https://app.wercker.com/project/bykey/6774907cc34f2b397f3b29e39948f799)
7 langreg is a lightweight Go package to handle ISO language and region (sometimes called country) codes. This only uses ISO 639-1 language codes, and ISO 3166-1 alpha-2 region codes. These are commonly used for language and region settings. E.g. `en_US`, `en_GB`, `zu_ZA`.
12 go get github.com/johngb/langreg
17 Language codes must be lowercase, while region codes must be uppercase (blame ISO for that).
19 With a language code, it is possible to:
21 - look up its English name
22 - look up its native name(s) in its native script(s)
24 With a region code, it is possible to:
26 - look up the English region name
30 The library is quite simple, but here are a few example use cases:
32 **Validate a composite (e.g. "en_US") code**
35 if langreg.IsValidLangRegCode(code) {
41 **Get a language in its native script**
44 name := langreg.LangNativeName(lang)
48 ```Result: 中文(Zhōngwén); 汉语; 漢語```
50 **Get a language in English**
53 name := langreg.LangEnglishName(lang)
62 region := langreg.RegionName(regCode)
71 All data sources that have been used are in the public domain.
73 The data used for the language codes and English names, come from the [official source](http://loc.gov/standards/iso639-2/ISO-639-2_utf-8.txt) at the Library of Congress. As the official specification doesn't include native names (What were they thinking?!), I've scraped the native names from Wikipedia's [list of ISO 639-1 codes](http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes).
75 As this is intended for general use cases, rather than distinguishing between ancient and modern languages, some of the names from the official source have been simplified where I felt they would be clear. For example "Greek, Modern (1453-)" - the official ISO name - is less clear than "Greek", and so I used "Greek". There are a few other minor cases like this, but nothing significant.
77 The data used for the region codes and data has been scraped from Wikipedia's [ISO 3166-1 page](http://en.wikipedia.org/wiki/ISO_3166-1). I couldn't find any single download from ISO without paying for it or scraping a page per letter of the alphabet, so I stuck with Wikipedia - because lazy.
79 ## Design and Benchmarks
81 This was designed primarily as a lightweight lookup table that would be called infrequently. I tested various options for this, and narrowed it down to either a map or a switch statement. The switch statement for a single lookup table was a little slower at 67-78 ns/op vs the maps' 38-50 ns/op, but had no data to load into memory first, while the startup time for loading the map into memory was 48 µs (48k ns).
83 Update: with some suggestions from @attilaolah to use nested switch statements, the switch version's performance is now significantly faster than even a pre-loaded map.
85 The worst case benchmarks results on a MacBook Pro are:
87 BenchmarkIsValidLangRegCode 100000000 23.2 ns/op
89 BenchmarkLangCodeInfo 100000000 10.7 ns/op
90 BenchmarkIsValidLanguageCode 100000000 11.2 ns/op
91 BenchmarkLangEnglishName 100000000 12.5 ns/op
92 BenchmarkLangNativeName 100000000 12.1 ns/op
94 BenchmarkRegionCodeInfo 200000000 9.73 ns/op
95 BenchmarkIsValidRegionCode 100000000 10.4 ns/op
96 BenchmarkRegionName 100000000 12.0 ns/op
101 This code is currently being used in a live environment, but should still be considered Alpha, as the code may still change.
105 The code has full test coverage of all logic functions, but due to the use of a long switch statement for the lookup table, it's not practial to test the full switch statement.
109 If you find any errors, or simply have constructive feedback, please post an issue directly, and I'll get to it as soon as I can.
113 The MIT License (MIT)
115 Copyright (c) 2014 John Beckett
117 Permission is hereby granted, free of charge, to any person obtaining a copy
118 of this software and associated documentation files (the "Software"), to deal
119 in the Software without restriction, including without limitation the rights
120 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
121 copies of the Software, and to permit persons to whom the Software is
122 furnished to do so, subject to the following conditions:
124 The above copyright notice and this permission notice shall be included in all
125 copies or substantial portions of the Software.
127 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
128 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
129 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
130 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
131 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
132 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE