= 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"]

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, ancient, 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

Add this line to your application’s Gemfile:
[source]
----
gem 'human_languages'
----

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.

.Retrieving single languages
[source]
----
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
[source]
Languages.all

.Get languages by name
[source]
----
Languages.search "^Germ"
Languages.search /\AJapan/
----

[CAUTION]
--
Passing a string to `Languages.search` results in case-sensitive search.
If case-insensitive search is intended, use ignorecase regexp like `/search_pattern/i` or pass optional `case_sensitive` parameter.
[source]
Languages.search('search_pattern', case_sensitive: false)
--

.Since ISO 639-3 categorizes the languages by scope and type, one can filter by them
[source]
----
# By scope
Languages.ancient
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`
[source]
Languages.all.select { |l| %w[ancient historical].include?(l.type) }

=== Data Objects

The `Language` objects have a simple read-only interface:

[source]
----
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 https://iso639-3.sil.org/about/scope#Macrolanguages[here].

[source]
----
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]