beygla v1.4.0

applyCase("ef", "Jóhannes");
//=> "Jóhannesar"

applyCase("þgf", "Helga Fríða Smáradóttir");
//=> "Helgu Fríðu Smáradóttur"

Overview

• Why does beygla exist?
• Usage
  • Cases
  • Whitespace
• Correctness
  • Strict mode
  • Passing a name in the wrong case
  • What happens if beygla does not find a pattern?

Icelandic names have four cases:

Guðmundur   →  Nominative case (nefnifall)
Guðmund     →  Accusative case (þolfall)
Guðmundi    →  Dative case (þágufall)
Guðmundar   →  Genitive case (eignarfall)

The different cases are used depending on the context in which the name is used.

• „Hann Guðmundur hefur bætt sig mikið.“
• „Illa er farið með góðan Guðmund.“
• „Hvað finnst Guðmundi um breytingarnar?“
• „Ég kem þessu áleiðis til Guðmundar.“

Icelandic usernames are stored in the nominative case (nefnifall). This can pose a challenge when using the name in a sentence.

The document has been sent to Guðmundur

Translated to Icelandic, this reads:

Skjalið hefur verið sent á Guðmundur

To an Icelander, this is jarring. The name appears in the nominative case „Guðmundur“, but it should be in the accusative case „Guðmund“.

Rewritten to use the nominative case, we get:

Guðmundur hefur fengið skjalið sent

But we've now changed the message entirely!

The document has been sent to Guðmundur

Guðmundur has received the document

This forces an Icelandic content writer to degrade the user experience by either

• using language that is not as natural, or
• reducing specificity by omitting the name entirely.

By being able to decline (transform) names to the correct case, we would remove this problem entirely.

Unfortunately, Icelandic name declension has lots of rules, with lots of exceptions.

# Left is nominative case, right is accusative case

Gauti → Gauta
Jóhanna → Jóhönnu
Snæfríður → Snæfríði
Alex → Alex
Bjarnfreður → Bjarnfreð

Encoding these rules, and their exceptions, is hard and can take up a lot of space. Developers don't want to add hundreds of kilobytes to the bundle size, just to apply cases to names.

Well, beygla encodes these rules in just 5 kilobytes gzipped.^*

^*: Declension rules are encoded using cases for 3647 out of 4505 Icelandic names (81%). The data for the cases is from bin.arnastofnun.is.

Install beygla as an npm package:

npm i -S beygla

Beygla exports a single function named applyCase.

import { applyCase } from "beygla";

applyCase("ef", "Jóhannes");
//=> "Jóhannesar"

applyCase("þgf", "Helga Dís Smáradóttir");
//=> "Helgu Dís Smáradóttur"

applyCase accepts two parameters: a case and a name (in the nominative case^nom).

The return value is a string with the name declined to the desired case.

^nom: If the provided name is not in the nominative case, applyCase is likely to yield an unexpected value.

The following cases may be provided as the first argument to applyCase:

If a case not in the table above is provided, "nf" is used as a fallback (i.e. nothing is done).

If the name includes superfluous whitespace, applyCase removes it.

applyCase("þgf", "  \n  Helga  Dís\tSmáradóttir  \n\n");
//=> "Helgu Dís Smáradóttur"

Beygla will correctly apply the desired case to the input name in most cases.

Most Icelandic names (81%), especially common ones, are present on bin.arnastofnun.is. Beygla is guaranteed to produce a correct result for those names.

This does not mean that Beygla produces an incorrect result for the other 19% of names. Beygla finds patterns in name endings based on the data on bin.arnastofnun.is and applies those patterns to any input name. This means that beygla will produce a correct result for most names, even if the name is not in the dataset from bin.arnastofnun.is.

I tried randomly sampling 20 names from the list of legal Icelandic names not present in bin.arnastofnun.is:

• 14 names matched a pattern with the correct result
• 6 names matched no pattern
• 0 names matched a pattern with an incorrect result

Even though I happened to get no incorrect results, this is a very small sample. I'm absolutely certain that there are a handful of names that will produce incorrect results.

See beygla.spec.ts.

Beygla provides a "strict version" accessible under beygla/strict which guarantees that declensions are only be applied to legal Icelandic names.

import { applyCase } from "beygla/strict";

The interface for beygla/strict is the exact same as for beygla.

Only declining Icelandic names may not be desirable when a correct declensions is not to applied to a foreign name. The beygla/strict module is also 15kB gzipped, which is three times larger than the standard beygla module.

Beygla operates on the assumption that names provided to it are in the nominative case (nefnifall). If a name provided to beygla is in another case than nominative, an incorrect result is extremely likely.

Given a name that has an ending that beygla does not recognize, it will not apply the case to the name.

Do note that beygla attempts to apply the case to every name (first, last, and middle name) in a full name individually. This means that some names in a full name might have a case applied, and some not.