Languages

Simple, dependency-less gem providing all known human languages^[1] defined in ISO 639-3

The ISO code set in data/ is taken from the official ISO 639-3 registration authority (ISO 639-3/RA) SIL International.

Installation

Add this line to your application’s Gemfile:

gem 'human_languages'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install human_languages

Usage

Foremost, load the gem

require 'languages'

Library Interface

The following examples show, how to get a language by its ISO 639-1 code, ISO 639-2 code, ISO 639-3 code, or by its (English) reference name. The codes should be passed as String or Symbol, whereby the casing in both options does not matter.

Retrieving single languages

german = Languages[:de]        # passing ISO 639-1 code returns the corresponding Language object
english = Languages[:eng]      # also works with ISO 639-2 and ISO 639-3 codes
italian = Languages['ita']     # even if passed as String

russian = Languages['Russian'] # Languages can be retrieved via reference name, too
klingon = Languages['KLINgon'] # weird casing, but still works

invalid = Languages[:invalid]  # invalid or unknown names or ISO codes returns nil

Get all ISO 639-3 languages

Languages.all

Get languages by name (regexp search)

Languages.search /Germ/i
Languages.search /\AJapan/

Caution

Searching languages by name is only allowed via Regexp that has been prepared and validated (if it comes from a untrusted user) in terms of case sensitivity and security / timeout. The support of passing search pattern of type String has been removed in v0.9.0. See #123 for more details.

Since ISO 639-3 categorizes the languages by scope and type, one can filter by them

# By scope
Languages.constructed
Languages.extinct
Languages.historical
Languages.living
Languages.special

# By languages types
Languages.individual_languages
Languages.macrolanguages
Languages.special_languages

Further custom language selections can be implemented using Languages.all

Languages.all.select { |l| %w[extinct historical].include?(l.type) }

Data Objects

The Language objects have a simple read-only interface:

language = Language[:fr]

language.name                 # => French
language.alpha2               # => :fr   (alias for #iso639_1)
language.alpha3               # => :fra  (alias for #iso639_3)
language.alpha3_bibliographic # => :fre  (alias for #iso_639_2b)
language.alpha3_terminology   # => :fra  (alias for #iso_639_2t)
language.type                 # => :living
language.scope                # => :individual

language.extinct?             # => false
language.living?              # => true
language.individual_language? # => true

Some languages of scope individual have a reference to their macrolanguage (scope `macrolanguage) that they belong to. More information on macrolanguages can be found here.

language = Language[:wuu]
language.individual_language? # => true

macrolanguage = language.macrolanguage

macrolanguage.alpha3        # => "zho"
macrolanguage.name          # => "Chinese"
macrolanguage.scope         # => :macrolanguage
macrolanguage.macrolanguage # => nil

Related Gems and Differences

Why to build another gem for ISO 639?

Table 1. Overview

Gem	ISO 639-1/-2	ISO 639-3	Translations	Data Storage
iso639	✅	❌	French	Collection of Hashes
iso-639	✅	❌	French	Array of Arrays
iso-639-data	✅	(✅) only scope individual	French for ISO 639-2	Hash of Hashes
language_list	✅	(✅) only scope individual	-	Array of Language-Objects
human_languages	✅	✅	-	Array of Language-Objects

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that allows you to experiment. To update and override the ISO 639-3 code table stored in data/ run bin/update-data.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Following Semantic Versioning 2.0.0.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/bbenno/languages.

Legal

The gem is

• available as open source under the terms of the MIT License.

• REUSE compliant

• uses ISO 639-3 code table from http://www.iso639-3.sil.org/ under their terms of use

---

1. This includes all individual languages already accounted for in ISO 639-2 as well as extinct, constructed, and historical languages.