feat: translations

TRANSLATIONS.md

@@ -0,0 +1,33 @@
+# Help us translate the fediseer FAQ
+
+We wish to allow the Fediseer [FAQ](/faq) to be available to multiple languages and for that we need your help.
+
+If you want to translate, you can do it two ways:
+
+
+## Pull Request
+
+Use this approach if you're good with github and/or git. If not, see the `Simple` approach below
+
+Go to our github repository (https://github.com/Fediseer/fediseer) and create a pull request for the language you would like to contribute.
+
+All you need to do is make a copy [of the english version](https://github.com/Fediseer/fediseer/blob/main/fediseer/faq/eng.py) into the [3-letter ISO 639-3 code](https://iso639-3.sil.org/code_tables/639/data) of the language you wish to translate to. 
+
+For example if you would like to translate into arabic, you would create a file `fediseer/faq/ara.py`.
+
+Then rename all variables of "ENG" to your language code. To follow our example, you would rename `ENG_HEADER` to `ARA_HEADER` before translating its contents.
+
+**Note:** Do not translate the `category` key. Only the `category_translated` key. 
+
+Once you're done with a field, change its `translated` key to `True`
+
+Finally in https://github.com/Fediseer/fediseer/blob/main/fediseer/faq/__init__.py, follow the other existing language as examples, and import and add the entries for your new language code.
+
+## Simple
+
+Use this approach if you don't understand github or git well.
+
+Simply [download the english version](https://github.com/Fediseer/fediseer/blob/main/fediseer/faq/eng.py)
+
+Edit it as best as you can with your text editor, then [open a new issue with your results](https://github.com/Fediseer/fediseer/issues) and post it there. We'll handle the rest. You can send us partial translations if you want and work on them slowly.
+

fediseer/apis/models/v1.py

@@ -143,6 +143,7 @@ class Models:
         self.response_model_faq_entry = api.model('FAQEntry', {
             'category': fields.String(description="The overarching category for this entry", example="terminology"),
             'category_translated': fields.String(description="The overarching category for this entry, translated to the target language.", example="terminology"),
+            'translated': fields.Boolean(description="If false, this entry has not yet been translated to the target language."),
             'added': fields.DateTime(description="The date this entry was added"),
             'question': fields.String(description="The entry in question form", example="What is an FAQ?"),
             'stub': fields.String(description="The entry in a short form", example="faq"),

fediseer/faq/__init__.py

@@ -1,7 +1,22 @@
-from .eng import ENG_FAQ
+from .eng import ENG_FAQ, ENG_HEADER, ENG_TRANSLATION_MESSAGE
-from .ell import ELL_FAQ
+from .ell import ELL_FAQ, ELL_HEADER, ELL_TRANSLATION_MESSAGE
+
+LANGUAGE_NAMES = {
+    "eng": "English",
+    "ell": "Ελληνικά",
+}
 
 FAQ_LANGUAGES = {
     "eng": ENG_FAQ,
     "ell": ELL_FAQ,
+}
+
+HEADER_LANGUAGES = {
+    "eng": ENG_HEADER,
+    "ell": ELL_HEADER,
+}
+
+TRANSLATION_MESSAGE_LANGUAGES = {
+    "eng": ENG_TRANSLATION_MESSAGE,
+    "ell": ELL_TRANSLATION_MESSAGE,
 }

fediseer/faq/ell.py

@@ -1,9 +1,19 @@
 from fediseer.consts import MAX_TAGS
 
+ELL_HEADER = """#Συχνές Ερωτήσεις για το Fediseer
+
+Αυτό το έγγραφο θα προσπαθήσει να παρέχει ορισμούς και απαντήσεις σε συνήθεις ερωτήσεις σχετικά με το Fediseer.
+
+[TOC]
+"""
+
+ELL_TRANSLATION_MESSAGE = "**Προσοχή**: Αυτή η μετάφραση δεν έχει υλοποιηθεί ακόμα."
+
 ELL_FAQ = [
     {
         "category": "terminology",
         "category_translated": "τερμινολογία",
+        "translated": True,
         "added": "2023-09-25",
         "question": "Τι είναι το Fediseer?",
         "stub": "fediseer",
@@ -21,6 +31,7 @@ To παρέχει ένα αναγνώσιμο από μηχανή API για τ
     {
         "category": "terminology",
         "category_translated": "τερμινολογία",
+        "translated": True,
         "added": "2023-09-25",
         "question": "Τι είναι η εγγυήση?",
         "stub": "guarantee",
@@ -39,6 +50,7 @@ To παρέχει ένα αναγνώσιμο από μηχανή API για τ
     {
         "category": "terminology",
         "category_translated": "τερμινολογία",
+        "translated": False,
         "added": "2023-09-25",
         "question": "What is the chain of trust?",
         "stub": "chain of trust",
@@ -53,6 +65,7 @@ This allows the fediseer to quickly deal with spam instances that sneaked into t
     {
         "category": "terminology",
         "category_translated": "τερμινολογία",
+        "translated": False,
         "added": "2023-09-25",
         "question": "What is an endorsement?",
         "stub": "endorsement",
@@ -67,6 +80,7 @@ When looking at the instance whitelist, one can also filter by amount of endorse
     {
         "category": "terminology",
         "category_translated": "τερμινολογία",
+        "translated": False,
         "added": "2023-09-25",
         "question": "What is a censure?",
         "stub": "censure",
@@ -81,6 +95,7 @@ One can export the list of instances censured by a subset of instances.
     {
         "category": "terminology",
         "category_translated": "τερμινολογία",
+        "translated": False,
         "added": "2023-09-25",
         "question": "What is a hesitation?",
         "stub": "hesitation",
@@ -95,6 +110,7 @@ One can export the list of instances hesitate by a subset of instances.
     {
         "category": "terminology",
         "category_translated": "τερμινολογία",
+        "translated": False,
         "added": "2023-09-25",
         "question": "What is an instance claim?",
         "stub": "claim",
@@ -107,6 +123,7 @@ Fediseer has no users. Instead it's driven by instance admins only. Instance adm
     {
         "category": "terminology",
         "category_translated": "τερμινολογία",
+        "translated": False,
         "added": "2023-09-25",
         "question": "What are instance visibilities?",
         "stub": "visibilities",
@@ -123,6 +140,7 @@ Note that guarantees are always public as this is necessary for the good functio
     {
         "category": "terminology",
         "category_translated": "τερμινολογία",
+        "translated": False,
         "added": "2023-09-25",
         "question": "What is an instance flag?",
         "stub": "flag",
@@ -136,6 +154,7 @@ Note that guarantees are always public as this is necessary for the good functio
     {
         "category": "terminology",
         "category_translated": "τερμινολογία",
+        "translated": False,
         "added": "2023-09-27",
         "question": "What is an instance tag?",
         "stub": "tag",
@@ -152,6 +171,7 @@ Like always, no hate speech is allowed.
     {
         "category": "functionality",
         "category_translated": "λειτουργικότητα",
+        "translated": False,
         "added": "2023-09-25",
         "question": "How can I claim my instance?",
         "stub": "instance claim",
@@ -164,6 +184,7 @@ You will then receive an API key in PMs, which you can afterwards use to represe
     {
         "category": "functionality",
         "category_translated": "λειτουργικότητα",
+        "translated": False,
         "added": "2023-09-25",
         "question": "What can I write in my reasons for endorsements, hesitations and censures?",
         "stub": "reasons",
@@ -176,6 +197,7 @@ You are not allowed to use hate speech in your reasons.
     {
         "category": "functionality",
         "category_translated": "λειτουργικότητα",
+        "translated": False,
         "added": "2023-09-25",
         "question": "What can I write in my evidence for censures and hesitations?",
         "stub": "evidence",
@@ -188,6 +210,7 @@ You are not allowed to use hate speech in your evidence.
     {
         "category": "philosophy",
         "category_translated": "φιλοσοφία",
+        "translated": False,
         "added": "2023-09-25",
         "question": "Doesn't this all cause fediverse centralization?",
         "stub": "centralization",
@@ -200,6 +223,7 @@ Not only that, but the fediseer is free and open source software, allowing anyon
     {
         "category": "philosophy",
         "category_translated": "φιλοσοφία",
+        "translated": False,
         "added": "2023-09-25",
         "question": "Doesn't this make the fediseer an authority on the fediverse?",
         "stub": "authority",

fediseer/faq/eng.py

@@ -1,9 +1,20 @@
 from fediseer.consts import MAX_TAGS
 
+ENG_HEADER = """#Fediseer FAQ
+
+This document will attempt to provide some definitions and answers to common questions around the fediseer.
+
+[TOC]
+"""
+
+ENG_TRANSLATION_MESSAGE = "**Attention**: This translation is not completed yet."
+
+
 ENG_FAQ = [
     {
         "category": "terminology",
         "category_translated": "terminology",
+        "translated": True,
         "added": "2023-09-25",
         "question": "What is the Fediseer?",
         "stub": "fediseer",
@@ -20,6 +31,7 @@ The fediseer provides a machine readable API to consume the data contained withi
     {
         "category": "terminology",
         "category_translated": "terminology",
+        "translated": True,
         "added": "2023-09-25",
         "question": "What is a guarantee?",
         "stub": "guarantee",
@@ -34,6 +46,7 @@ Guarantees are community driven. While the fediseer can guarantee at the top lev
     {
         "category": "terminology",
         "category_translated": "terminology",
+        "translated": True,
         "added": "2023-09-25",
         "question": "What is the chain of trust?",
         "stub": "chain of trust",
@@ -48,6 +61,7 @@ This allows the fediseer to quickly deal with spam instances that sneaked into t
     {
         "category": "terminology",
         "category_translated": "terminology",
+        "translated": True,
         "added": "2023-09-25",
         "question": "What is an endorsement?",
         "stub": "endorsement",
@@ -62,6 +76,7 @@ When looking at the instance whitelist, one can also filter by amount of endorse
     {
         "category": "terminology",
         "category_translated": "terminology",
+        "translated": True,
         "added": "2023-09-25",
         "question": "What is a censure?",
         "stub": "censure",
@@ -76,6 +91,7 @@ One can export the list of instances censured by a subset of instances.
     {
         "category": "terminology",
         "category_translated": "terminology",
+        "translated": True,
         "added": "2023-09-25",
         "question": "What is a hesitation?",
         "stub": "hesitation",
@@ -90,6 +106,7 @@ One can export the list of instances hesitate by a subset of instances.
     {
         "category": "terminology",
         "category_translated": "terminology",
+        "translated": True,
         "added": "2023-09-25",
         "question": "What is an instance claim?",
         "stub": "claim",
@@ -102,6 +119,7 @@ Fediseer has no users. Instead it's driven by instance admins only. Instance adm
     {
         "category": "terminology",
         "category_translated": "terminology",
+        "translated": True,
         "added": "2023-09-25",
         "question": "What are instance visibilities?",
         "stub": "visibilities",
@@ -118,6 +136,7 @@ Note that guarantees are always public as this is necessary for the good functio
     {
         "category": "terminology",
         "category_translated": "terminology",
+        "translated": True,
         "added": "2023-09-25",
         "question": "What is an instance flag?",
         "stub": "flag",
@@ -131,6 +150,7 @@ Note that guarantees are always public as this is necessary for the good functio
     {
         "category": "terminology",
         "category_translated": "terminology",
+        "translated": True,
         "added": "2023-09-27",
         "question": "What is an instance tag?",
         "stub": "tag",
@@ -147,6 +167,7 @@ Like always, no hate speech is allowed.
     {
         "category": "functionality",
         "category_translated": "functionality",
+        "translated": True,
         "added": "2023-09-25",
         "question": "How can I claim my instance?",
         "stub": "instance claim",
@@ -159,6 +180,7 @@ You will then receive an API key in PMs, which you can afterwards use to represe
     {
         "category": "functionality",
         "category_translated": "functionality",
+        "translated": True,
         "added": "2023-09-25",
         "question": "What can I write in my reasons for endorsements, hesitations and censures?",
         "stub": "reasons",
@@ -171,6 +193,7 @@ You are not allowed to use hate speech in your reasons.
     {
         "category": "functionality",
         "category_translated": "functionality",
+        "translated": True,
         "added": "2023-09-25",
         "question": "What can I write in my evidence for censures and hesitations?",
         "stub": "evidence",
@@ -183,6 +206,7 @@ You are not allowed to use hate speech in your evidence.
     {
         "category": "philosophy",
         "category_translated": "philosophy",
+        "translated": True,
         "added": "2023-09-25",
         "question": "Doesn't this all cause fediverse centralization?",
         "stub": "centralization",
@@ -195,6 +219,7 @@ Not only that, but the fediseer is free and open source software, allowing anyon
     {
         "category": "philosophy",
         "category_translated": "philosophy",
+        "translated": True,
         "added": "2023-09-25",
         "question": "Doesn't this make the fediseer an authority on the fediverse?",
         "stub": "authority",

fediseer/routes.py

@@ -2,7 +2,7 @@ from flask import render_template, redirect, url_for, request
 from markdown import markdown
 from loguru import logger
 from fediseer.flask import OVERSEER
-from fediseer.faq import FAQ_LANGUAGES
+from fediseer.faq import FAQ_LANGUAGES, HEADER_LANGUAGES, TRANSLATION_MESSAGE_LANGUAGES, LANGUAGE_NAMES
 import fediseer.exceptions as e
 
 @logger.catch(reraise=True)
@@ -34,12 +34,12 @@ def index():
     return(head + markdown(findex))
 
 @logger.catch(reraise=True)
-@OVERSEER.route('/faq')
+@OVERSEER.route('/faq/<lang>')
 # @cache.cached(timeout=300)
-def faq():
+def faq(lang):
-    with open(f'fediseer/templates/faq.md') as md_file:
+    if lang not in FAQ_LANGUAGES:
-        md = md_file.read()
+        return redirect(url_for('faq_default'))
-
+    md = HEADER_LANGUAGES[lang]
     style = """<style>
         body {
             max-width: 120ex;
@@ -59,16 +59,48 @@ def faq():
     </head>
     """
     faq_dict = {}
-    for entry in FAQ_LANGUAGES["eng"]:
+    for entry in FAQ_LANGUAGES[lang]:
-        if entry["category"] not in faq_dict:
+        if entry["category_translated"] not in faq_dict:
-            faq_dict[entry["category"]] = []
+            faq_dict[entry["category_translated"]] = []
-        faq_dict[entry["category"]].append(entry)
+        faq_dict[entry["category_translated"]].append(entry)
     for category in faq_dict:
         md += f"#{category.capitalize()}\n\n"
         for entry in faq_dict[category]:
-            md += f"## {entry['question']}\n\n{entry['document']}"
+            md += f"## {entry['question']}\n"
-    return(head + markdown(md, extensions=['toc']
+            if entry["translated"] is False:
-))
+                md += f"{TRANSLATION_MESSAGE_LANGUAGES[lang]}\n\n"
+            md += f"{entry['document']}"
+    return(head + markdown(md, extensions=['toc']))
+
+@logger.catch(reraise=True)
+@OVERSEER.route('/faq')
+@OVERSEER.route('/faq/')
+def faq_default():
+    style = """<style>
+        body {
+            max-width: 120ex;
+            margin: 0 auto;
+            color: #333333;
+            line-height: 1.4;
+            font-family: sans-serif;
+            padding: 1em;
+        }
+        </style>
+    """
+
+    head = f"""<head>
+    <title>Fediseer</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    {style}
+    </head>
+    """
+    md = "#Fediseer FAQ\n\n" +\
+        "We provide the fediseer FAQ in multiple languages. Please select one of the options below.\n\n"
+
+    for lang in LANGUAGE_NAMES:
+        md += f"   * [{LANGUAGE_NAMES[lang]}](/faq/{lang})\n"
+    md += "\nPlease [help us add more language support](https://github.com/Fediseer/fediseer/blob/main/TRANSLATIONS.md)"
+    return(head + markdown(md))
 
 @logger.catch(reraise=True)
 @OVERSEER.route('/.well-known/webfinger')

fediseer/templates/faq.md

@@ -1,6 +0,0 @@
-# Fediseer FAQ
-
-This document will attempt to provide some definitions and answers to common questions around the fediseer.
-
-[TOC]
-