2. 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.
Note
Please only participate in beta if you can set up LinguaCafe yourself, you can create a backup of your database, and if you don't mind encountering more issues than main version releases, including bugs that can corrupt your database. I'll always try to help if you encounter issues, but I have limited time, and it may take a few days before I can check out problems.
The beta docker image is a version of LinguaCafe that I use in my personal production environment. Previously I only tested it for a few days, but since I have less time nowadays, LinguaCafe has more users, and I am trying to develop it while maintaining a more stable version than did before, I will test updates for a bit longer.
To use the beta version of LinguaCafe, create a .env file in your LinguaCafe directory if you don't already have one, and add this line to the end of it: VERSION=beta. After that run the update command of your operating system from the readme file. It will pull the latest beta docker image.
To see if a new beta version is released, you can just run the update command, or check the GitHub actions page. I may change it up, but at this time there's no other way to track beta releases. Since the latest beta image will become the main version, there's no reason to move back to the main version, except if you want to stop using the beta when the next version comes out.
I created this docker image because I've seen people using unsupported features, and wanting to use the latest version as soon as possible. If you decide to use it, please backup before every update. Also keep in mind that reverting to older versions is not supported.
If there ever will be extra steps necessary for beta users, I will display that in this section.
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/storagedirectory, which stores your files. -
linguacafe/databasedirectory, 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.
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.
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`
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.
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 workto words such asworked. - Gender tagging: In gendered and supported languages, LinguaCafe will prepend nouns with additional information based on the words' gender.
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.
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.
- Download the dictionaries that you want to use from the provided links below.
- Copy the dictionary files to your
linguacafe/storage/app/dictionariesfolder. - Go to the Admin > Dictionaries page in LinguaCafe, and click on the Import dictionary button.
- This dialog will list all your importable dictionaries that are found in your
dictionariesfolder. 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.
| 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
You can also import a custom dictionary file in the form of a .csv file.
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.
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.
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.
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.
- Create an API key in Jellyfin. You can do this on the Dashboard > API Keys menu.
- Set the created API key in LinguaCafe on to the Admin > API menu.
- 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.
- Save the settings.
Now you can import subtitles from Jellyfin.
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.