README.md

   1 # iso-codes
   2
   3 https://salsa.debian.org/iso-codes-team/iso-codes
   4
   5 This project provides lists of various ISO standards (e.g. country,
   6 language, language scripts, and currency names) in one place, rather
   7 than repeated in many programs throughout the system.
   8
   9 Currently there are lists of languages and countries embedded in
  10 several different programs, which leads to dozens of lists of
  11 200 languages, translated into more than 90 languages ... not
  12 very efficient.
  13
  14 With this project, we create a single "gettext domain" for every
  15 supported ISO standard which contains the translations of
  16 that domain. It is easy for a programmer to re-use those
  17 translations instead of maintaining their own translation
  18 infrastructure. Moreover, the programmer does not need to follow
  19 changes in the ISO standard and will not work with outdated
  20 information.
  21
  22 To use this translation infrastructure, the programmer just needs
  23 to call `dgettext()` in their program.
  24
  25 Example:
  26
  27 ```
  28 dgettext("iso_639-2", "French")
  29 ```
  30
  31 will return the translation for "French", depending on the
  32 current locale.
  33
  34 Furthermore, this project provides the ISO standards as JSON files
  35 to be used by other applications as well. All those JSON files
  36 are stored in the directory "/usr/share/iso-codes/json".
  37
  38 # Status of translations
  39
  40 Below you can see the current translation status, with the two most
  41 important gettext domains listed first (countries and languages).
  42
  43 * ISO 3166-1 (countries):
  44
  45   [![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)
  46
  47 * ISO 639-2 (languages):
  48
  49   [![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)
  50
  51 The other gettext domains are also useful, but probably
  52 not as important as the first two.
  53
  54 * ISO 4217 (currencies):
  55
  56   [![Translation status](https://hosted.weblate.org/widgets/iso-codes/-/iso-4217/287x66-white.png)](https://hosted.weblate.org/engage/iso-codes/?utm_source=widget)
  57
  58 * ISO 3166-2 (countries and subdivisions):
  59
  60   [![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)
  61
  62 * ISO 3166-3 (formerly used country codes):
  63
  64   [![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)
  65
  66 * ISO 639-3 (languages):
  67
  68   [![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)
  69
  70 * ISO 639-5 (language families and groups):
  71
  72   [![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)
  73
  74 * ISO 15924 (script names):
  75
  76   [![Translation status](https://hosted.weblate.org/widgets/iso-codes/-/iso-15924/287x66-white.png)](https://hosted.weblate.org/engage/iso-codes/?utm_source=widget)
  77
  78 # NEWS
  79
  80 * A new ISO standard has been included, ISO 3166-3. The gettext
  81   domain is called `iso_3166-3`. Basically, this is a split of the
  82   old domain `iso_3166` into `iso_3166-1` and `iso_3166-3`, because
  83   the old domain `iso_3166` contained both standards. However, the
  84   standard ISO 3166-3 was more or less inaccessible.
  85 * The standard ISO 4217 (currency names) now includes only the
  86   currently used currencies. Entries of withdrawn currencies are
  87   no longer included.
  88 * The standard ISO 639-5 now includes only the language families
  89   which are part of the official standard. The previously
  90   included languages were not part of the standard and have been
  91   removed. This reduced the number of language families from
  92   about 1900 to about 110.
  93 * The XML files are **deprecated** and should not be used for new
  94   projects. However, they are kept in sync with the JSON data
  95   for now.
  96 * The gettext domains have been renamed to better match the
  97   actual ISO number:
  98   - ISO 639-2: Renamed from `iso_639` to `iso_639-2`
  99   - ISO 639-3: Renamed from `iso_639_3` to `iso_639-3`
 100   - ISO 639-5: Renamed from `iso_639_5` to `iso_639-5`
 101   - ISO 3166-1: Renamed from `iso_3166` to `iso_3166-1`
 102   - ISO 3166-2: Renamed from `iso_3166_2` to `iso_3166-2`
 103
 104   All previously used gettext domains are linked to the new
 105   domain names, so that this transition should be smooth for
 106   programs using those domain names.
 107
 108
 109 ## ISO 639-2
 110
 111 This lists the 2-letter and 3-letter language codes and language
 112 names. The official ISO 639-2 maintenance agency is the Library of
 113 Congress. The gettext domain is "iso_639-2".
 114
 115 <http://www.loc.gov/standards/iso639-2/>
 116
 117
 118 ## ISO 639-3
 119
 120 This is a further development of ISO 639-2, see above. All codes
 121 of ISO 639-2 are included in ISO 639-3. ISO 639-3 attempts to
 122 provide as complete an enumeration of languages as possible,
 123 including living, extinct, ancient, and constructed languages,
 124 whether major or minor, written or unwritten. The gettext
 125 domain is "iso_639-3". The official ISO 639-3 maintenance agency
 126 is SIL International.
 127
 128 <http://www.sil.org/iso639-3/>
 129
 130
 131 ## ISO 639-5
 132
 133 This standard is highly incomplete list of alpha-3 codes
 134 for language families and groups. The official ISO 639-5 maintenance
 135 agency is the Library of Congress. The gettext domain is "iso_639-5".
 136
 137 <http://www.loc.gov/standards/iso639-5/>
 138
 139
 140 ## ISO 3166-1
 141
 142 This lists the 2-letter country code and "short" country name. The
 143 official ISO 3166-1 maintenance agency is ISO. The gettext domain is
 144 "iso_3166-1".
 145
 146 <http://www.iso.org/iso/country_codes>
 147
 148
 149 ## ISO 3166-2
 150
 151 The ISO 3166 standard includes a "Country Subdivision Code",
 152 giving a code for the names of the principal administrative
 153 subdivisions of the countries coded in ISO 3166. The official
 154 ISO 3166-2 maintenance agency is ISO. The gettext domain is
 155 "iso_3166-2".
 156
 157 <http://www.iso.org/iso/country_codes>
 158
 159
 160 ## ISO 3166-3
 161
 162 The ISO 3166-3 standard defines codes for country names which
 163 have been removed from ISO 3166-1. The official ISO 3166-3
 164 maintenance agency is ISO. The gettext domain is "iso_3166-3".
 165
 166 <http://www.iso.org/iso/country_codes>
 167
 168
 169 ## ISO 4217
 170
 171 This lists the currency codes and names. The official ISO 4217
 172 maintenance agency is the Swiss Association for Standardization.
 173 The gettext domain is "iso_4217".
 174
 175 <http://www.currency-iso.org/en/home.html>
 176
 177
 178 ## ISO 15924
 179
 180 This lists the language scripts names. The official ISO 15924
 181 maintenance agency is the Unicode Consortium. The gettext
 182 domain is "iso_15924".
 183
 184 <http://unicode.org/iso15924/>
 185
 186
 187 # Tracking updates to the various ISO standards
 188
 189 Below is a list of websites we use to check for updates to the
 190 standards.
 191
 192 ISO 639-2:
 193 <http://www.loc.gov/standards/iso639-2/php/code_changes.php>
 194
 195 ISO 639-3:
 196 <http://www-01.sil.org/iso639-3/changes.asp>
 197
 198 ISO 639-5:
 199 <http://www.loc.gov/standards/iso639-5/changes.php>
 200
 201 ISO 3166-1, ISO 3166-2, and ISO 3166-3:
 202 <http://www.iso.org/iso/country_codes>
 203
 204 ISO 4217:
 205 <http://www.currency-iso.org/en/home/tables/table-a1.html>
 206
 207 ISO-15924:
 208 <http://unicode.org/iso15924/codechanges.html>
 209
 210
 211 # Adding or updating translations
 212
 213 The iso-codes project uses the Weblate translation service
 214 as the primary way of managing translations.
 215 You can find more information about this on the website:
 216
 217 <https://hosted.weblate.org/projects/iso-codes/>
 218
 219 You can also send your translation as a bug report against the package
 220 iso-codes to the Debian Bug Tracking System. You can either send an email
 221 or use the tool reportbug. More details are on this website:
 222
 223 <https://bugs.debian.org/>
 224
 225
 226 # Reporting a bug
 227
 228 If you find a bug in iso-codes, there are several ways to contact us.
 229
 230 * Salsa issues
 231
 232   <https://salsa.debian.org/iso-codes-team/iso-codes/issues>
 233
 234   This system can be accessed via webbrowser.
 235 * Debian Bug Tracking System
 236
 237   <https://bugs.debian.org/>
 238
 239   This system can be accessed via e-mail.
 240
 241
 242 # Developing using pkgconfig
 243
 244 A pkgconfig file has been included to aid developing with this
 245 project. You can detect the prefix where the translations have
 246 been placed using
 247
 248 ```
 249 $ pkg-config --variable=prefix iso-codes
 250 /usr
 251 ```
 252
 253 You can detect which gettext domains have been installed using
 254
 255 ```
 256 $ pkg-config --variable=domains iso-codes
 257 iso_639-2 iso_639-3 iso_639-5 iso_3166-1 iso_3166-2 iso_3166-3 iso_4217 iso_15924
 258 ```