reling 1.6.1

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.

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.

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

Installation

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

Without Audio 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 Grammar Support

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

pipx install "reling[grammar]"

With Both Audio and Grammar Support

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

pipx install "reling[audio,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.

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 100 predefined options will be chosen.

style

You may also choose a style for the text. If unspecified, a random style from 25 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 20 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] [--read fr] [--listen] [--hide-prompts] [--model <GPT-MODEL>] [--tts-model <TTS-MODEL>] [--asr-model <ASR-MODEL>] [--api-key <OPENAI-KEY>]

Content ID

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

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.

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.

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).

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]

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.

Learning Statistics

reling stats

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

reling stats en [--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.

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).

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 and taking exams (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.