README.md 7.91 KB
Newer Older
1
# iso-codes
Tobias Quathamer's avatar
Tobias Quathamer committed
2

3
https://salsa.debian.org/iso-codes-team/iso-codes
Tobias Quathamer's avatar
Tobias Quathamer committed
4

5
This project provides lists of various ISO standards (e.g. country,
6 7
language, language scripts, and currency names) in one place, rather
than repeated in many programs throughout the system.
Tobias Quathamer's avatar
Tobias Quathamer committed
8

9 10
Currently there are lists of languages and countries embedded in
several different programs, which leads to dozens of lists of
11
200 languages, translated into more than 90 languages ... not
12
very efficient.
Alastair McKinstry's avatar
Alastair McKinstry committed
13

14
With this project, we create a single "gettext domain" for every
15 16 17 18 19 20
supported ISO standard which contains the translations of
that domain. It is easy for a programmer to re-use those
translations instead of maintaining their own translation
infrastructure. Moreover, the programmer does not need to follow
changes in the ISO standard and will not work with outdated
information.
Alastair McKinstry's avatar
Alastair McKinstry committed
21

22
To use this translation infrastructure, the programmer just needs
Tobias Quathamer's avatar
Tobias Quathamer committed
23
to call `dgettext()` in their program.
Alastair McKinstry's avatar
Alastair McKinstry committed
24

25
Example:
Tobias Quathamer's avatar
Tobias Quathamer committed
26

27 28 29
```
dgettext("iso_639-2", "French")
```
Tobias Quathamer's avatar
Tobias Quathamer committed
30

31 32
will return the translation for "French", depending on the
current locale.
Alastair McKinstry's avatar
Alastair McKinstry committed
33

34
Furthermore, this project provides the ISO standards as JSON files
Tobias Quathamer's avatar
Tobias Quathamer committed
35 36 37
to be used by other applications as well. All those JSON files
are stored in the directory "/usr/share/iso-codes/json".

38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60
# Status of translations

Below you can see the current translation status, with the two most
important gettext domains listed first (countries and languages).

[![Translation status](https://hosted.weblate.org/widgets/iso-codes/-/iso-3166-1/287x66-white.png)](https://hosted.weblate.org/engage/iso-codes/?utm_source=widget)

[![Translation status](https://hosted.weblate.org/widgets/iso-codes/-/iso-639-2/287x66-white.png)](https://hosted.weblate.org/engage/iso-codes/?utm_source=widget)

The other gettext domains are also useful, but probably
not as important as the first two.

[![Translation status](https://hosted.weblate.org/widgets/iso-codes/-/iso-4217/287x66-white.png)](https://hosted.weblate.org/engage/iso-codes/?utm_source=widget)

[![Translation status](https://hosted.weblate.org/widgets/iso-codes/-/iso-3166-2/287x66-white.png)](https://hosted.weblate.org/engage/iso-codes/?utm_source=widget)

[![Translation status](https://hosted.weblate.org/widgets/iso-codes/-/iso-3166-3/287x66-white.png)](https://hosted.weblate.org/engage/iso-codes/?utm_source=widget)

[![Translation status](https://hosted.weblate.org/widgets/iso-codes/-/iso-639-3/287x66-white.png)](https://hosted.weblate.org/engage/iso-codes/?utm_source=widget)

[![Translation status](https://hosted.weblate.org/widgets/iso-codes/-/iso-639-5/287x66-white.png)](https://hosted.weblate.org/engage/iso-codes/?utm_source=widget)

[![Translation status](https://hosted.weblate.org/widgets/iso-codes/-/iso-15924/287x66-white.png)](https://hosted.weblate.org/engage/iso-codes/?utm_source=widget)
Tobias Quathamer's avatar
Tobias Quathamer committed
61

62
# NEWS
Tobias Quathamer's avatar
Tobias Quathamer committed
63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86

* A new ISO standard has been included, ISO 3166-3. The gettext
  domain is called `iso_3166-3`. Basically, this is a split of the
  old domain `iso_3166` into `iso_3166-1` and `iso_3166-3`, because
  the old domain `iso_3166` contained both standards. However, the
  standard ISO 3166-3 was more or less inaccessible.
* The standard ISO 4217 (currency names) now includes only the
  currently used currencies. Entries of withdrawn currencies are
  no longer included.
* The standard ISO 639-5 now includes only the language families
  which are part of the official standard. The previously
  included languages were not part of the standard and have been
  removed. This reduced the number of language families from
  about 1900 to about 110.
* The XML files are **deprecated** and should not be used for new
  projects. However, they are kept in sync with the JSON data
  for now.
* The gettext domains have been renamed to better match the
  actual ISO number:
  - ISO 639-2: Renamed from `iso_639` to `iso_639-2`
  - ISO 639-3: Renamed from `iso_639_3` to `iso_639-3`
  - ISO 639-5: Renamed from `iso_639_5` to `iso_639-5`
  - ISO 3166-1: Renamed from `iso_3166` to `iso_3166-1`
  - ISO 3166-2: Renamed from `iso_3166_2` to `iso_3166-2`
87

Tobias Quathamer's avatar
Tobias Quathamer committed
88 89 90 91 92
  All previously used gettext domains are linked to the new
  domain names, so that this transition should be smooth for
  programs using those domain names.


93
## ISO 639-2
Tobias Quathamer's avatar
Tobias Quathamer committed
94 95 96 97

This lists the 2-letter and 3-letter language codes and language
names. The official ISO 639-2 maintenance agency is the Library of
Congress. The gettext domain is "iso_639-2".
Alastair McKinstry's avatar
Alastair McKinstry committed
98

Tobias Quathamer's avatar
Tobias Quathamer committed
99
<http://www.loc.gov/standards/iso639-2/>
Alastair McKinstry's avatar
Alastair McKinstry committed
100

101

102
## ISO 639-3
103

Tobias Quathamer's avatar
Tobias Quathamer committed
104 105 106 107 108 109 110 111 112
This is a further development of ISO 639-2, see above. All codes
of ISO 639-2 are included in ISO 639-3. ISO 639-3 attempts to
provide as complete an enumeration of languages as possible,
including living, extinct, ancient, and constructed languages,
whether major or minor, written or unwritten. The gettext
domain is "iso_639-3". The official ISO 639-3 maintenance agency
is SIL International.

<http://www.sil.org/iso639-3/>
113

114

115
## ISO 639-5
116

Tobias Quathamer's avatar
Tobias Quathamer committed
117 118 119
This standard is highly incomplete list of alpha-3 codes
for language families and groups. The official ISO 639-5 maintenance
agency is the Library of Congress. The gettext domain is "iso_639-5".
120

Tobias Quathamer's avatar
Tobias Quathamer committed
121 122 123
<http://www.loc.gov/standards/iso639-5/>


124
## ISO 3166-1
Alastair McKinstry's avatar
Alastair McKinstry committed
125

126
This lists the 2-letter country code and "short" country name. The
Tobias Quathamer's avatar
Tobias Quathamer committed
127 128 129
official ISO 3166-1 maintenance agency is ISO. The gettext domain is
"iso_3166-1".

130
<http://www.iso.org/iso/country_codes>
Alastair McKinstry's avatar
Alastair McKinstry committed
131 132


133
## ISO 3166-2
Alastair McKinstry's avatar
Alastair McKinstry committed
134

Tobias Quathamer's avatar
Tobias Quathamer committed
135 136 137 138 139
The ISO 3166 standard includes a "Country Subdivision Code",
giving a code for the names of the principal administrative
subdivisions of the countries coded in ISO 3166. The official
ISO 3166-2 maintenance agency is ISO. The gettext domain is
"iso_3166-2".
140

Tobias Quathamer's avatar
Tobias Quathamer committed
141
<http://www.iso.org/iso/country_codes>
142 143


144
## ISO 3166-3
Tobias Quathamer's avatar
Tobias Quathamer committed
145 146 147 148 149 150

The ISO 3166-3 standard defines codes for country names which
have been removed from ISO 3166-1. The official ISO 3166-3
maintenance agency is ISO. The gettext domain is "iso_3166-3".

<http://www.iso.org/iso/country_codes>
151 152


153
## ISO 4217
154

155
This lists the currency codes and names. The official ISO 4217
Tobias Quathamer's avatar
Tobias Quathamer committed
156 157 158 159
maintenance agency is the Swiss Association for Standardization.
The gettext domain is "iso_4217".

<http://www.currency-iso.org/en/home.html>
160

161

162
## ISO 15924
163 164 165 166

This lists the language scripts names. The official ISO 15924
maintenance agency is the Unicode Consortium. The gettext
domain is "iso_15924".
Alastair McKinstry's avatar
Alastair McKinstry committed
167

Tobias Quathamer's avatar
Tobias Quathamer committed
168
<http://unicode.org/iso15924/>
Alastair McKinstry's avatar
Alastair McKinstry committed
169 170


171
# Tracking updates to the various ISO standards
172 173

Below is a list of websites we use to check for updates to the
Tobias Quathamer's avatar
Tobias Quathamer committed
174
standards.
175

Tobias Quathamer's avatar
Tobias Quathamer committed
176 177
ISO 639-2:
<http://www.loc.gov/standards/iso639-2/php/code_changes.php>
178 179

ISO 639-3:
Tobias Quathamer's avatar
Tobias Quathamer committed
180 181 182 183 184 185 186 187 188 189
<http://www-01.sil.org/iso639-3/changes.asp>

ISO 639-5:
<http://www.loc.gov/standards/iso639-5/changes.php>

ISO 3166-1, ISO 3166-2, and ISO 3166-3:
<http://www.iso.org/iso/country_codes>

ISO 4217:
<http://www.currency-iso.org/en/home/tables/table-a1.html>
190 191

ISO-15924:
Tobias Quathamer's avatar
Tobias Quathamer committed
192
<http://unicode.org/iso15924/codechanges.html>
193 194


195 196 197 198 199
# Adding or updating translations

The iso-codes project uses the Weblate translation service
as the primary way of managing translations.
You can find more information about this on the website:
200

201 202 203
<https://hosted.weblate.org/projects/iso-codes/>

You can also send your translation as a bug report against the package
204 205 206
iso-codes to the Debian Bug Tracking System. You can either send an email
or use the tool reportbug. More details are on this website:

Tobias Quathamer's avatar
Tobias Quathamer committed
207
<https://bugs.debian.org/>
208

209

210
# Reporting a bug
211

212
If you find a bug in iso-codes, there are several ways to contact us.
213

214
* Salsa issues
215

216
  <https://salsa.debian.org/iso-codes-team/iso-codes/issues>
217 218 219

  This system can be accessed via webbrowser.
* Debian Bug Tracking System
220

Tobias Quathamer's avatar
Tobias Quathamer committed
221
  <https://bugs.debian.org/>
222

223 224
  This system can be accessed via e-mail.

Alastair McKinstry's avatar
Alastair McKinstry committed
225

226
# Developing using pkgconfig
227 228

A pkgconfig file has been included to aid developing with this
229
project. You can detect the prefix where the translations have
230
been placed using
Alastair McKinstry's avatar
Alastair McKinstry committed
231

232 233 234 235
```
$ pkg-config --variable=prefix iso-codes
/usr
```
Alastair McKinstry's avatar
Alastair McKinstry committed
236

237
You can detect which gettext domains have been installed using
Alastair McKinstry's avatar
Alastair McKinstry committed
238

239 240 241 242
```
$ pkg-config --variable=domains iso-codes
iso_639-2 iso_639-3 iso_639-5 iso_3166-1 iso_3166-2 iso_3166-3 iso_4217 iso_15924
```