Skip to content

2. Setup

Jump to bottom
simjanos-dev edited this page Apr 25, 2024 · 4 revisions

Setup

This section contains information related to hosting, setting up and maintaining your LinguaCafe server. There are some important steps to take after installation before you can use linguacafe, like installing additional languages and importing dictionaries.

Backup

Note

This guide assumes you named your directory linguacafe during installation. If you used a different name for your directory, simply replace linguacafe with it.

LinguaCafe stores your data in two directories:

  • linguacafe/storage directory, which stores your files.
  • linguacafe/database directory, which stores your database files.

Both must be saved to preserve all your LinguaCafe data.

To make a backup of your LinguaCafe instance, simply copy your whole linguacafe directory. On Linux you may need root privileges to copy the database folder, so please make sure that it was successful. Also make sure that the permissions are the same after restoring your data. You can reapply them by using the chmod command from the installation guide.

To ensure that your installed language models works, you must restart your docker container after restoring a backup.

Note

Backup your database regularly! I highly recommend making regular backups, especially before upgrading LinguaCafe to a newer version. LinguaCafe is still in active development, and there is a high possibility of introducing a data corrupting bug.

Exporting the LinguaCafe's database

Although copying the whole database folder works, you might also want to make a raw export of your database in order to remove the dependency on a functioning MySql docker container. This way you can have your database data in a single .sql file, e.g., linguacafe-backup.sql.

Note

If you run docker ps -a, then you should get all running Docker containers, among which there's linguacafe-database or a similarly named container, in which the database is running.

Run this command while your LinguaCafe server is running to export your database:

docker exec DATABASE-CONTAINER mysqldump --no-tablespaces -uUSERNAME -pPASSWORD DATABASE > ./linguacafe-backup.sql

where DATABASE-CONTAINER, USERNAME, and PASSWORD should be replaced with the names you used during installation. If you kept the default names, then the command is simply:

docker exec linguacafe-database mysqldump --no-tablespaces -ulinguacafe -plinguacafe linguacafe > ./linguacafe-backup.sql

Now there should be a linguacafe-backup.sql file inside your current directory.

Importing the LinguaCafe's database

You can import the database back with the following command:

docker exec -i DATABASE-CONTAINER mysql -uUSERNAME -pPASSWORD DATABASE < ./linguacafe-backup.sql`

where DATABASE-CONTAINER, USERNAME, and PASSWORD should be replaced with the names you used during installation. If you kept the default names, then the command is simply:

docker exec -i linguacafe-database mysql -ulinguacafe -plinguacafe linguacafe < ./linguacafe-backup.sql`

Updating

When a new version of LinguaCafe is released, please create a backup, and read the GitHub Release notes and the main GitHub Readme file's update section before updating. If there is an important or a breaking change in the update, it will be noted in those places.

Caution

LinguaCafe is still in active development, and it will change from month to month. Please make sure you backup your data regularly, and expect updates to have possible problems.

Languages

In LinguaCafe all the data are separated by the selected language. This means that any action you take in one language will not affect the data in other languages, so the first thing you should do in LinguaCafe is select your target language. You can change your selected language by clicking on the flag in the bottom left corner.

When you import text, LinguaCafe does:

  • Lemma generation: When you import a text into LinguaCafe, the text processor will automatically assign dictionary form to words for supported languages. For example, it will assign the lemma to work to words such as worked.
  • Gender tagging: In gendered and supported languages, LinguaCafe will prepend nouns with additional information based on the words' gender.

Installing languages

Some languages are not packaged in the docker image. These languages can be installed on the Admin > Languages page. Installing a language can take several minutes, and requires internet connection. Installed languages are being saved into the storage directory.

Uninstalling languages are only possible by uninstalling all the installed languages.

Supported Languages

LinguaCafe supports the following languages:

Flag Language DeepL Lemma generation Gender tagging Dictionaries
Chinese ✓ wiktionary, cc-cedict
Croatian ✓ dict cc
Czech ✓ wiktionary, dict cc
Danish ✓ ✓ wiktionary, dict cc
Dutch ✓ ✓ dict cc
English ✓ ✓ dict cc
Finnish ✓ inaccurate wiktionary, dict cc
French ✓ ✓ wiktionary, dict cc
German ✓ ✓ ✓ wiktionary, dict cc
Greek ✓ ✓ wiktionary, dict cc
Italian ✓ ✓ wiktionary, dict cc
Japanese ✓ ✓ jmdict, wiktionary
Korean ✓ ✓ wiktionary, kengdic
Latin wiktionary
Macedonian ✓ wiktionary
Norwegian ✓ ✓ ✓ wiktionary, dict cc
Polish ✓ ✓ wiktionary, dict cc
Portuguese ✓ ✓ wiktionary, dict cc
Romanian ✓ ✓ wiktionary, dict cc
Russian ✓ ✓ wiktionary, dict cc
Slovenian ✓ ✓ wiktionary
Spanish ✓ ✓ wiktionary, dict cc
Swedish ✓ ✓ dict cc
Thai wiktionary
Turkish ✓ ✓ wiktionary, dict cc
Ukrainian ✓ wiktionary
Welsh wiktionary, eurfa

Note

For Chinese only Mandarin language is supported with simplified Chinese characters.

Importing dictionaries

  1. Download the dictionaries that you want to use from the provided links below.
  2. Copy the dictionary files to your linguacafe/storage/app/dictionaries folder.
  3. Go to the Admin > Dictionaries page in LinguaCafe, and click on the Import dictionary button.
  4. This dialog will list all your importable dictionaries that are found in your dictionaries folder. Click on the Import button for the dictionary that you want to import.

After the import process is finished, your dictionary should be available whenever you select a word while reading.

Caution

Do not rename any dictionary files. For some dictionaries the filename is used to identify them.

Dictionaries

Dictionary Languages Download Comment
JMDict Japanese GitHub release This dictionary contains kanji and radicals for the Japanese language. Some Japanese features do not work without importing this dictionary.
CC-CEDICT Chinese GitHub release
Kengdic Korean GitHub release
Eurfa Welsh GitHub release
Wiktionary Chinese, Czech, Finnish, French, German, Italian, Japanese, Korean, Norwegian, Russian, Spanish, Ukrainian, Welsh GitHub release
Dict.cc Czech, Dutch, Finnish, French, German, Italian, Norwegian, Russian, Spanish, Swedish dict.cc

Note

To import JMDict you must download all 4 of these files: jmdict_processed.txt, kanjidic2.xml, radical-strokes.txt, radicals.txt

Custom dictionary

You can also import a custom dictionary file in the form of a .csv file.

DeepL translate

DeepL is a machine translation service that lets you translate up to 500.000 characters/month for free and is supported by LinguaCafe. To access the Deepl API, you'll need to create an API key, add it in Admin > API > DeepL, and enable the DeepL dictionary.

Importing Vocabulary into LinguaCafe

If you have a list of words that you already know before you started using LinguaCafe, you can import them from a CSV file.

Note

 Changes after importing cannot be reverted, thus make sure you're importing only the words you want LinguaCafe to track.

To import words, go to the Vocabulary page, select the Data dropdown menu, and inside that click on the Import button. On the import dialog you can select your CSV file and a few options:

  • Skip first row. If enabled, LinguaCafe skips the first row which could be simply be the column names.
  • Only update. If enabled, no new words will be added to the system. This allows you to only update fields for words that you have already encountered in LinguaCafe.

The CSV file can have these columns, in this order:

Column Name Required Accepted Values Comment
Word Yes Any word without any spaces.
Translation No Can be left empty.
Lemma No Can be left empty.
Reading No Can be left empty.
Lemma reading No Can be left empty.
Level No new, ignored, learned, 1, 2, 3, 4, 5, 6, 7 Cannot be left empty.

At least the first column must be present in the CSV file. Any further columns can be added to it in the order showed above. If a column is not provided, those fields will not be changed in the database. However if a column is provided, and it's left empty in a row, it will be overwritten in the database with an empty value.

After the import is complete, you will see a message about the number of created, updated and rejected words.

Anki

Currently Anki is supported if your server and Anki run on the same PC and have the AnkiConnect plugin installed.

To set up an Anki's connection, head over to Admin > API > Anki.

Note

Future versions of LinguaCafe won't have this requirement.

Jellyfin

You can use the network configuration from this example to connect Jellyfin's network with LinguaCafe. There are probably multiple ways to do it, the only requirement is that linguacafe-webserver should be able to reach Jellyfin's server to make API requests.

version: '3.5'
networks:
    linguacafe_linguacafe:
        external: true

services:
    jellyfin:
        image: jellyfin/jellyfin
        container_name: jellyfin
        user: 1000:1000
        volumes:
            - /path/to/config:/config
            - /path/to/cache:/cache
            - /path/to/media:/media:ro
        restart: 'unless-stopped'
        ports:
            - 8096:8096
        networks:
            - linguacafe_linguacafe

You must name your subtitle files in a way that Jellyfin will recognize as languages. These worked for me:

Series Name - S01E01.ja.ass  
Series Name - S01E01.de.ass  
Movie name.es.ass

Language codes for subtitle filenames that Jellyfin recognizes:

Language Language Code
Chinese zh
Croatian hr
Czech cs
Danish da
Dutch nl
Finnish fi
French fr
German de
Italian it
Japanese ja
Korean ko
Macedonian mk
Norwegian no
Polish pl
Portuguese pt
Romanian ro
Russian ru
Slovenian sl
Spanish es
Swedish sv
Thai th
Turkish tr
Ukrainian uk
Welsh cy

See Jellyfin external file naming.

Jellyfin API usage

  1. Create an API key in Jellyfin. You can do this on the Dashboard > API Keys menu.
  2. Set the created API key in LinguaCafe on to the Admin > API menu.
  3. Set the Jellyfin host in LinguaCafe on to the Admin > API menu. If you used the pre-written configs, it should be the default http://jellyfin:8096.
  4. Save the settings.

Now you can import subtitles from Jellyfin.

Jellyfin troubleshooting

Possible error codes in browser console while importing from Jellyfin:

Error: unsupported language code: spa

This means that Jellyfin recognized the language of the subtitle, but it is not supported by LinguaCafe yet. If you find one of these, please open a GitHub Issue, this should be fixed.

Error: unsupported language code: unrecognized by jellyfin: japaaaneseee

This means that Jellyfin did not recognize japaaaneseee as a language, and it can only be fixed by renaming the file following Jellyfin's naming conventions.

If you have file naming issues and renamed a file, make sure you refresh metadata in Jellyfin before reloading LinguaCafe.

Clone this wiki locally