add Character data type

docs/courses/course.md

@@ -112,7 +112,7 @@ Modules:
   - `License > Name`: Full license name under which your course is made available. In most cases, it's ok to keep it as is.
   - `License > Short name`: Short name for the license, e.g., `CC BY-SA 4.0`
   - `License > Link`: URL to reach the full text of the license, e.g., `https://creativecommons.org/licenses/by-sa/4.0/legalcode`
-- `Special characters`: An array of special characters that might not be present on a typical English keyboard.
+- `Special characters`: An array of special characters that might not be present on a typical English keyboard. Note that this is separate from `New Characters` included inside some skills.
 
 **`Modules`** has a list of module directory names followed by a `/`.
 

docs/courses/skill.md

@@ -110,6 +110,16 @@ Two-way-dictionary:
   - the man: L'homme
 ```
 
+Additionally, characters which are unfamiliar to the person learning the new language can be included in skills. These are typically put above `New Words` in a `(skill_name).yaml` file.
+
+```yaml
+New Characters:
+
+  - Character: ç
+    Transliteration: s
+    IPA: /ç/
+```
+
 ### Data breakdown
 
 **`Skill`** has information about the skill.
@@ -118,6 +128,12 @@ Two-way-dictionary:
 - `Skill > Id`: The ID of the course. **NOTE:** This should be unchanged if you're translating or editing an existing course. Only if you're creating a new course should this have a unique [UUID v4](https://www.uuidgenerator.net/version4) string. Details for which you can find [here](creating-courses.md).
 - `Skill > Thumbnails`: A list of filenames of the thumbnails to be used on the course page to give an idea of the skill. A list of available files can be found on [`apps/web/static/images/`](https://github.com/LibreLingo/LibreLingo/tree/main/apps/web/static/images). The names should be used without extension and without `_tiny` or `_tinier` parts, e.g., `banana2_tinier.jpg` should be written as `banana2`.
 
+**`New Characters`** has a list of new characters that the lesson teaches. This is only used for languages which use different characters than what the learner already knows. A character in LibreLingo can be a single character or a sound blend. These are currently not implemented in the web app.
+
+- `Character`: The new character. Ensure it has the correct unicode value so it displays correctly.
+- `Transliteration`: A list of transliterations of this character in the source language's script. The first one will be taught.
+- `IPA`: A list of pronounciations in IPA (Internation Phonetic Language) format. (optional)
+
 **`New words`** has a list of new words that the lesson teaches.
 
 - `Word`: The word in the target language, i.e., the language the user is learning.

src/librelingo_types/data_types.py

@@ -215,6 +215,7 @@ class Skill(
             "id",
             "words",
             "phrases",
+            "characters",
             "image_set",
             "dictionary",
             "introduction",
@@ -237,6 +238,7 @@ class Skill(
         id="3adc78da-ea42-4ecd-9e3d-2e0986a3b914",
         words=[word1, word2, word3],
         phrases=[phrases1, phrases2, phrases3],
+        characters=[character1, character2, character3]
         image_set=["cat1", "dog2", "horse1"],
         dictionary=[dict_item_1, dict_item_2, dict_item_3, dict_item_4],
         introduction="My *markdown* text",
@@ -321,6 +323,35 @@ class Phrase(
 
     pass
 
+class Character(
+    namedtuple("Character", ["character", "transliteration", "ipa_pronounciation"])
+):
+    """
+    A new character taught in a LibreLingo skill. These are used for teaching 
+    languages which use a different script or characters than what the learner's
+    source language uses. These are taught in lessons using the transliteration(s)
+    and pronounciation of the character and it's sounds.
+
+    A character in LibreLingo could either be a single character, or a combination
+    of characters, depending on what makes sense for that specific language. There
+    should be two Character entries if a letter has both lowercase and uppercase.
+
+    ipa_pronounciation is how the character is written in the Internation Phonetic
+    Alphabet (IPA). It is a list as in many languages a character can represent 
+    several sounds. Knowing this can help with pronounciation or differentiating 
+    similar characters and sound blends. Read the Wikipedia article on 
+    https://en.wikipedia.org/wiki/International_Phonetic_Alphabet. 
+
+    A long sound macron on an 'a' in Te Reo Māori
+    >>> Character("ā", ["aa"], ["/aː/"])
+    Character(character='ā', transliteration=['aa'], ipa_pronounciation=['/aː/'])
+
+    The Г character in Ukranian (which uses the Cyrillic script).
+    >>> Character("Г", ["H"], ["/ɦ/"])
+    Character(character='Г', transliteration=['H'], ipa_pronounciation=['/ɦ/'])
+    """
+
+    pass
 
 class DictionaryItem(
     namedtuple("DictionaryItem", ["word", "definition", "is_in_target_language"])