reling 1.15.4

Command-line tool for learning foreign languages through iterative translation with AI-generated feedback

ReLing: Command-line Tool for Learning Foreign Languages

ReLing allows you to learn or enhance your knowledge of any major world language supported by GPT models. To use this tool, you must have a paid OpenAI account with an API key created.

The program operates as follows:

• Select a GPT model to generate a text or dialogue on a chosen or random topic.
• View or translate the generated content into any supported language.
• Take an exam to translate the text from one language to another and receive:
  • A score for each sentence on a 10-point scale;
  • Suggestions for improving your translations;
  • The program’s own translation of the sentence.

You can retake exams at your preferred frequency until you achieve perfect scores. Once satisfied with your performance, you can archive the content and optionally use it later for spaced repetition.

ReLing also enables you to view a list of all generated texts and dialogues and their associated exam histories.

Optionally, the system can vocalize sentences in both the source and target languages and accept your responses via voice or image capture.

Table of Contents

• Installation
• Generating Texts
• Generating Dialogues
• Displaying Content
• Taking Exams
• Exam History
• Learning Statistics
• Listing Content
• Archiving Content
• Unarchiving Content
• Renaming Content
• Deleting Content
• Exporting Data
• Automatic Content ID
• Languages
• Setting Models and API Key
• Specifying Genders
• Acknowledgements

Installation

Install Python 3.12 or higher and pipx, then proceed based on your audio, image, and grammar preferences:

Without Audio, Image, or Grammar Support

pipx install reling

With Audio Support

On macOS, first install Homebrew, then:

brew install portaudio

On Ubuntu, run:

sudo apt install python3-pyaudio

Install the tool with the audio extra:

pipx install "reling[audio]"

With Image Support

If you want to use the image scanning feature, install the tool with the image extra:

pipx install "reling[image]"

With Grammar Support

If you want to track grammar-related learning statistics, install the tool with the grammar extra:

pipx install "reling[grammar]"

With Audio, Image, and Grammar Support

Follow the instructions above to install the necessary dependencies, then run the following command:

pipx install "reling[audio,image,grammar]"

Finalizing Setup

You may need to restart your terminal for the reling command to be recognized.

Additionally, to enable command-line completions, execute:

reling --install-completion

For Mac users, you may also need to append compinit -D to the end of your ~/.zshrc file.

Updating the Tool

To update ReLing to its latest version, run:

pipx upgrade reling

Uninstalling the Tool

To remove ReLing from your system, execute:

pipx uninstall reling

This will uninstall the tool but will not delete your data storage file. If you wish to delete this file as well, you must remove it manually.

Generating Texts

reling create text

The command format is:

reling create text en [--level basic] [--topic food] [--style news] [--size 5] [--include "cook: a person"] [--model <GPT-MODEL>] [--api-key <OPENAI-KEY>]

Language

Specify a supported language as the only positional argument. The text will be in that language but can be translated later.

level

Choose from three complexity levels:

• basic;
• intermediate (default);
• advanced.

topic

You may select a topic for the text. If unspecified, a random topic from 500 predefined options will be chosen.

style

You may also choose a style for the text. If unspecified, a random style from 50 predefined options will be chosen.

size

This sets the number of sentences in the text. By default, 10 sentences are generated.

include

This parameter allows you to ensure the inclusion of specific vocabulary in the text. You can specify a simple word (--include cook), a word with a specific meaning (--include "cook: a person"), or several words or phrases (--include "cook: a person" --include soup --include "mac and cheese").

model & api-key

Refer to Setting Models and API Key.

Generating Dialogues

reling create dialogue

The command format is:

reling create dialogue en [--level advanced] [--speaker waiter] [--topic food] [--size 5] [--include "cook: a person"] [--speaker-gender male] [--user-gender female] [--model <GPT-MODEL>] [--api-key <OPENAI-KEY>]

Language

Specify a supported language as the only positional argument. The dialogue will be generated in this language and can be translated later.

level

Choose from three complexity levels:

• basic;
• intermediate (default);
• advanced.

speaker

Specify an interlocutor or let the system choose randomly from 200 predefined options.

topic

Choose a topic for the dialogue or let it be automatically determined.

size

This parameter sets the number of sentence pairs in the dialogue. The default is 10.

include

This parameter allows you to ensure the inclusion of specific vocabulary in the dialogue. You can specify a simple word (--include cook), a word with a specific meaning (--include "cook: a person"), or several words or phrases (--include "cook: a person" --include soup --include "mac and cheese").

speaker-gender & user-gender

Refer to Specifying Genders.

If the interlocutor’s gender is not specified, it will be randomly chosen as either male or female.

model & api-key

Refer to Setting Models and API Key.

Displaying Content

reling show

View or listen to a text or dialogue with:

reling show <CONTENT-ID> [en] [--read] [--model <GPT-MODEL>] [--tts-model <TTS-MODEL>] [--api-key <OPENAI-KEY>]

Content ID

Specify the identifier of the content to view. This ID is provided when content is created and listed.

Language

Optionally, specify a language to view the content in that language, translating if necessary.

read

If enabled, the content will be read aloud. You can stop the reading at any time by pressing Ctrl + C.

model, tts-model & api-key

Refer to Setting Models and API Key.

Taking Exams

reling exam

To translate a text or dialogue and receive feedback, run:

reling exam <CONTENT-ID> [--from en] [--to fr] [--skip 3] [--read fr] [--listen] [--scan 0] [--hide-prompts] [--offline-scoring] [--retry] [--model <GPT-MODEL>] [--tts-model <TTS-MODEL>] [--asr-model <ASR-MODEL>] [--api-key <OPENAI-KEY>]

While inputting your answers during an exam, you can press Ctrl + C to pause. This affects the calculation of exam duration and, consequently, your learning statistics.

Content ID

Specify the content identifier for the exam. This ID is provided when content is created and listed.

You may use a dot (.) to refer to the last text or dialogue you interacted with or just created.

Use two dots (..) to activate the spaced repetition mode, which automatically selects an archived text or dialogue for the exam, based on the source and/or target language (if any of them is provided). Only sentences currently in the learning queue will be evaluated. A sentence is added to the queue if the last answer was not perfect or if the time elapsed since the last answer exceeds the duration between that answer and the start of the most recent streak of perfect answers; the minimum time, however, is always one hour.

from & to

Specify the languages from which and to which you would like to translate the text or dialogue. If one of the languages is not specified, the original language of the selected text or dialogue will be used.

skip

This parameter allows you to skip sentences after achieving a specified number of consecutive perfect answers in prior attempts (for the given pair of source and target languages).

read

Optionally, you can specify one or both of the selected source and target languages to have the text read aloud. For example, use --read en --read fr to hear the content in English and French. You can stop the reading at any time by pressing Ctrl + C.

listen

When this flag is enabled, ReLing will accept your responses via voice. You also have the option to switch to manual input mode if needed.

scan

Use this parameter to have ReLing accept your response by capturing an image with one of the available cameras. The value of the parameter is the index of the camera to use. For example, camera 0 might be your laptop’s built-in camera, while camera 1 could be an external webcam or a connected smartphone.

You also have the option to switch to manual input mode if needed.

hide-prompts

This flag allows you to hide the original language text as well as the interlocutor’s turn (if in a dialogue). It can help train recall or listening skills (when the listen flag is enabled).

offline-scoring

Use this flag to score answers based on an offline algorithm instead of the OpenAI API.

retry

If this flag is enabled, the system will automatically retry each sentence until you either:

• Achieve a perfect score (10/10), or
• Submit a blank input to skip further retries.

If multiple attempts are made, the best translation (highest score) will be saved in the exam history.

model, tts-model, asr-model & api-key

Refer to Setting Models and API Key.

Exam History

reling history

To view your exam history, use the command:

reling history <CONTENT-ID> [--from en] [--to fr] [--answers]

Content ID

Specify the identifier of the text or dialogue whose exam history you wish to review.

from & to

Limit the display of exam results to translations between specified source and target languages.

answers

Use this flag to view your answers and corresponding scores for each sentence.

Learning Statistics

reling stats

The stats command provides detailed statistics about your learning progress in specific languages. The command format is:

reling stats en [--pair fr] [--grammar] [--comprehension] [--production] [--checkpoint 2024-12-01] [--checkpoint "2025-01-01, 15:00"]

Language

Specify a supported language as the only positional argument. The statistics will be shown for this language.

pair

Optionally, specify one or more languages such that the statistics will be displayed for translations between the main language and these languages only.

If you need to specify more than one language, use the --pair flag multiple times: --pair fr --pair es.

grammar

Use this flag to view statistics on learned word forms and lemmas, classified by part of speech. If this flag is not used, general statistics, such as total time spent in exams, will be displayed. Note that to use this flag, you must install the tool with the grammar extra.

comprehension & production

You can request statistics related to either comprehension or production, or both. By default, both are displayed unless one is specifically requested.

checkpoint

Optionally, provide one or more date checkpoints (in YYYY-MM-DD or YYYY-MM-DD, HH:MM format) to see progress since those points in time.

Listing Content

reling list

To view a list of all generated texts and dialogues, execute:

reling list [--category dialogue] [--level intermediate] [--language en] [--search <REGEX>] [--archive] [--ids-only]

category

Choose to display either texts or dialogues.

level

Filter content by complexity level: basic, intermediate, or advanced.

language

Display content generated in a specific language.

search

Use a regular expression to search content IDs, text, topics, styles, or interlocutors.

archive

Toggle to view content from the archive.

ids-only

Display only the identifiers of texts and dialogues without full details.

Archiving Content

reling archive

To archive texts and dialogues:

reling archive <CONTENT-ID>

Content ID

Provide the identifier of the content you wish to archive.

Unarchiving Content

reling unarchive

To restore archived content to the main list:

reling unarchive <CONTENT-ID>

Content ID

Specify the identifier of the content to be restored from the archive.

Renaming Content

reling rename

To rename a specific text or dialogue:

reling rename <CONTENT-ID> <NEW-ID>

Content ID

Enter the identifier of the content you want to rename.

New ID

Provide the new identifier for the content.

Deleting Content

reling delete

To remove texts or dialogues permanently:

reling delete <CONTENT-ID> [--force]

Content ID

Specify the identifier of the content you intend to delete.

force

Enable immediate deletion without confirmation.

Exporting Data

reling db

To access the data storage file for transferring or backing up content and exam results:

reling db

Automatic Content ID

If a dot (.) is provided in place of a content ID in any command, the system will assume that you are referring to the last text or dialogue you interacted with.

Languages

ReLing supports over 180 major languages sourced from Wikipedia under the CC BY-SA 4.0 license.

To specify a language in a command argument, you can either write its full name (e.g., English or english) or use the 2-character or 3-character code for that language (e.g., en or eng for English).

For languages written in multiple scripts, the system does not currently support specifying a particular script in the commands. The script used will depend on GPT’s output and may vary. Additionally, for right-to-left scripts such as Arabic or Hebrew, punctuation is likely to display incorrectly. If you plan to use the tool with these languages, feel free to request a fix or contribute a solution.

Setting Models and API Key

To avoid specifying model names and entering the API key separately for each command, you can set the following environment variables:

• RELING_API_KEY: a pre-generated API key for OpenAI’s web API.
• RELING_MODEL: the name of the GPT model used for generating text, taking exams, and scanning images (e.g., gpt-4o).
• RELING_TTS_MODEL: the name of the text-to-speech (TTS) model (e.g., tts-1). Since current OpenAI TTS models primarily focus on English and may not perform well in other languages, you can use the additional model _gtts (Google Text-to-Speech) for better voice output in other languages (note the leading underscore).
• RELING_ASR_MODEL: the name of the automatic speech recognition (ASR) model for voice response recognition (e.g., whisper-1).

Parameter values specified in individual commands will take precedence over these environment variables.

If a model or key is not specified in either the command or the environment variable, the program will prompt you to enter it directly.

Specifying Genders

The system requires knowledge of your gender and the gender of your interlocutor to accurately generate dialogues in languages with grammatical gender and to provide voice outputs with appropriate voices.

To avoid specifying your gender each time you generate a new dialogue, you can set the environment variable RELING_USER_GENDER.

The system accepts one of the following values for gender: male, female, or nonbinary.

Acknowledgements

Thank you to Tamila Krashtan for assisting with testing and suggesting improvements to ReLing.