= Languages Benno Bielmeier :source-language: ruby
image:https://api.reuse.software/badge/github.com/bbenno/languages[link="https://api.reuse.software/info/github.com/bbenno/languages", alt="REUSE status"] image:https://badge.fury.io/rb/human_languages.svg["Gem Version", link="https://badge.fury.io/rb/human_languages"]
image:https://img.shields.io/maintenance/yes/2024[Maintenance] image:https://github.com/bbenno/languages/actions/workflows/main.yml/badge.svg[link="https://github.com/bbenno/languages/actions/workflows/main.yml"]
![https://github.com/bbenno/languages/actions/workflows/main.yml/badge.svg[link="https://github.com/bbenno/languages/actions/workflows/main.yml"]](https://github.com/bbenno/languages/actions/workflows/main.yml/badge.svg%5Blink=%22https://github.com/bbenno/languages/actions/workflows/main.yml%22%5D){kind=link}
Simple, dependency-less gem providing all known human languagesfootnote:[This includes all individual languages already accounted for in ISO 639-2 as well as extinct, constructed, and historical languages.] defined in ISO 639-3
The ISO code set in link:data/[data/] is taken from the official ISO 639-3 registration authority (ISO 639-3/RA) https://iso639-3.sil.org/[SIL International].
== Installation
And then execute: .... $ bundle install ....
Or install it yourself as: .... $ gem install human_languages ....
== Usage
.Foremost, load the gem [source] 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.
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
.Get all ISO 639-3 languages [source] Languages.all
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 https://github.com/bbenno/languages/pull/123[#123] for more details.
Languages.constructed Languages.extinct Languages.historical Languages.living Languages.special
.Further custom language selections can be implemented using Languages.all
[source]
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
Some languages of scope individual have a reference to their macrolanguage (scope `macrolanguage) that they belong to.
More information on macrolanguages can be found https://iso639-3.sil.org/about/scope#Macrolanguages[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?
.Overview [%header,cols="2,1,2,2,3"] |=== |Gem |ISO 639-1/-2 |ISO 639-3 |Translations |Data Storage
|https://rubygems.org/gems/iso639[iso639] |✅ |❌ |French |Collection of Hashes
|https://rubygems.org/gems/iso-639[iso-639] |✅ |❌ |French |Array of Arrays
|https://rubygems.org/gems/iso-639-data[iso-639-data] |✅ |(✅) only scope individual |French for ISO 639-2 |Hash of Hashes
|https://rubygems.org/gems/language_list[language_list] |✅
| (✅) only scope individual |
|---|
| Array of Language-Objects |
|https://rubygems.org/gems/human_languages[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 link:data/[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 https://rubygems.org[rubygems.org].
Following https://semver.org/[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 https://opensource.org/licenses/MIT[MIT License].
- https://reuse.software/[REUSE] compliant
- uses ISO 639-3 code table from http://www.iso639-3.sil.org/ under their https://iso639-3.sil.org/code_tables/download_tables#termsofuse[terms of use]