Skip to content

Latest commit

 

History

History
198 lines (151 loc) · 5.83 KB

README.adoc

File metadata and controls

198 lines (151 loc) · 5.83 KB
Raw

Languages

REUSE status Gem Version

Maintenance badge

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.

Contributing

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

Legal

The gem is

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