Beygla

Tiny (5kB gzipped) declension helper for Icelandic names

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

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

Overview

• Why does beygla exist?
• Usage
  • Cases
  • Whitespace

Why does beygla exist?

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óðann 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!

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.

Usage

Install beygla as an npm package:

npm i -S beygla

Beygla exports a single function named applyCase.

import { applyCase } from "beygla";

applyCase("ef", "Jóhann");
//=> "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.

Cases

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).

Whitespace

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"