Skip to content
NHCarrigan Logo NHCarrigan Docs

Aria Iuvo

Aria Iuvo (hereinafter the “Application”) is a Discord bot designed to provide seamless message translation capabilities using LibreTranslate. The bot allows users to translate Discord messages to their preferred language through an intuitive right-click context menu interface. Developed by NHCarrigan, Aria Iuvo supports over 25 languages and offers both free and premium functionality through Discord’s subscription system.

1. User Documentation

This section is for those interacting with a live instance of the Application.

Getting Started

To use Aria Iuvo, add the bot to your Discord account using the provided authorization link. The bot operates as a user-installable application, meaning it can be used across any Discord server or direct message where you have access.

Core Features

Message Translation

  • Context Menu Access: Right-click on any message, select “Apps”, then choose “Translate Message”
  • Automatic Language Detection: The bot automatically detects the source language of the message
  • User Locale Targeting: Messages are translated to your Discord interface language
  • Confidence Reporting: Translation results include the detection confidence percentage

About Command

  • Use the /about slash command to view bot information
  • Displays current version, commit hash, and helpful links
  • Available in 25+ languages matching your Discord locale

Premium Features

  • Subscription Required: Message translation requires an active premium subscription
  • Subscription Management: Use the premium button in bot responses to manage subscriptions

Supported Languages

Aria Iuvo supports translation between the following languages:

  • English (en)
  • Spanish (es)
  • French (Français)
  • German (Deutsch)
  • Italian (Italiano)
  • Portuguese (pt)
  • Russian (Русский)
  • Chinese Simplified (zh)
  • Chinese Traditional (zt)
  • Japanese (日本語)
  • Korean (한국어)
  • Dutch (Nederlands)
  • Polish (Polski)
  • Czech (Čeština)
  • Danish (Dansk)
  • Swedish (Svenska)
  • Finnish (Suomi)
  • Greek (Ελληνικά)
  • Bulgarian (Български)
  • Romanian (Română)
  • Hungarian (Magyar)
  • Lithuanian (Lietuvių)
  • Ukrainian (Українська)
  • Turkish (Türkçe)
  • Thai (ไทย)
  • Hindi (हिन्दी)
  • Indonesian (Bahasa Indonesia)

Error Handling

  • No Message Content: The bot will notify you if the selected message contains no translatable text
  • Unsupported Language: If your locale isn’t supported, you’ll receive a notification
  • Network Issues: Connection problems are logged and users receive error notifications
  • Rate Limiting: The bot handles API rate limits gracefully

2. Technical Documentation

This section is for those interested in running their own instance of the Application.

System Architecture

Aria Iuvo is built using modern TypeScript and Node.js technologies with the following key components:

Core Technologies

  • Runtime: Node.js with ES modules
  • Language: TypeScript with strict configuration
  • Discord Library: discord.js v14+
  • Translation Service: LibreTranslate API
  • Web Framework: Fastify (for health monitoring)
  • Package Manager: pnpm

Project Structure

src/
├── index.ts                    # Main entry point and Discord client setup
├── commands/                   # Slash command definitions
│   ├── about.ts               # About command configuration
│   └── translate.ts           # Context menu command configuration
├── modules/                    # Core functionality implementations
│   ├── about.ts               # About command logic
│   ├── translate.ts           # Translation processing logic
│   └── getLocale.ts           # Locale resolution utilities
├── config/                     # Configuration files
│   └── locales.ts             # Supported locales and mappings
├── i18n/                      # Internationalization
│   └── responses.ts           # Localized response strings
├── server/                     # Web server components
│   └── serve.ts               # Health monitoring server
└── utils/                      # Utility functions
    ├── i18n.ts                # Translation utilities
    ├── logger.ts              # Logging functionality
    └── replyToError.ts        # Error response handling

Environment Setup

Required Environment Variables

Terminal window
DISCORD_TOKEN=your_discord_bot_token
TRANSLATE_TOKEN=your_libretranslate_api_key

Installation Steps

  1. Clone the repository
  2. Install dependencies: pnpm install
  3. Configure environment variables
  4. Build the project: pnpm run build
  5. Start the application: pnpm run start

Development Workflow

  • Linting: pnpm run lint (ESLint with @nhcarrigan/eslint-config)
  • Testing: pnpm run test (Vitest with coverage)
  • Building: pnpm run build (TypeScript compilation)

API Integration

LibreTranslate Service

  • Detection Endpoint: https://trans.nhcarrigan.com/detect
  • Translation Endpoint: https://trans.nhcarrigan.com/translate
  • Authentication: API key-based authentication
  • Request Format: URL-encoded form data

Discord Integration

  • Application Type: User-installable bot
  • Interaction Types: Message context menus, slash commands
  • Permission Model: Minimal intents required (no message content access)
  • Premium Integration: Discord’s SKU-based subscription system

Monitoring and Health Checks

Web Server

  • Port: 5001
  • Endpoint: / (serves HTML status page)
  • Framework: Fastify with logging disabled
  • Purpose: Health monitoring and basic bot information

Logging System

  • Error Handling: Comprehensive error logging with structured data
  • Process Monitoring: Unhandled rejection and exception tracking
  • Subscription Events: User subscription/unsubscription logging

Deployment Considerations

Production Requirements

  • Node.js 22+ runtime environment
  • Access to LibreTranslate API service
  • Discord bot token with appropriate permissions
  • Environment variable management (1Password integration shown)

Scaling Considerations

  • Stateless design enables horizontal scaling
  • Rate limiting handled at API level
  • Minimal memory footprint due to no message caching

This section is for expansions to our legal policies specific to the Application.

Licensing

Aria Iuvo is licensed under Naomi’s Public License, as referenced in the global software license documentation available at docs.nhcarrigan.com.

Data Handling

Message Processing

  • Temporary Processing: Messages are sent to LibreTranslate for translation only
  • No Storage: The bot does not store or cache message content
  • Ephemeral Responses: All bot responses are ephemeral (only visible to the requesting user)

User Data

  • Minimal Collection: Only Discord user IDs and locale preferences are processed
  • Subscription Data: Premium subscription status is managed through Discord’s system
  • No Personal Information: No additional personal data is collected or stored

Third-Party Services

  • LibreTranslate: Message content is temporarily sent to LibreTranslate for processing
  • Discord: All interactions are governed by Discord’s Terms of Service and Privacy Policy

4. Contributing Documentation

This section is for documentation related to contributing to the Application’s codebase.

Development Environment

Prerequisites

  • Node.js 22 or higher
  • pnpm package manager
  • Git version control
  • TypeScript knowledge
  • Discord.js familiarity

Code Standards

  • Linting: ESLint with @nhcarrigan/eslint-config
  • Type Safety: Strict TypeScript configuration
  • Testing: Vitest with coverage requirements
  • Documentation: JSDoc comments for all public functions

Contribution Workflow

Getting Started

  1. Fork the repository
  2. Create a feature branch from main
  3. Set up development environment
  4. Make your changes following code standards
  5. Run tests and linting
  6. Submit a pull request

Code Style Guidelines

  • Naming Conventions: camelCase for variables, PascalCase for types
  • File Organization: Logical separation by functionality
  • Import Style: ES modules with explicit extensions
  • Error Handling: Comprehensive try-catch blocks with logging

Internationalization (i18n)

Adding New Languages
  1. Add locale to supportedLocales array in config/locales.ts
  2. Add mapping if needed in mappedLocales object
  3. Add translations to responses object in i18n/responses.ts
  4. Update command localizations in commands/ files
Translation Structure
[Locale.NewLanguage]: {
  "button": {
    code:    "Source Code Translation",
    support: "Help Translation",
  },
  "command-error": "Error message translation",
  "embed": {
    commit:      "Commit translation",
    description: "Bot description translation",
    title:       "About title translation",
    version:     "Version translation",
  },
  "no-message-content":    "No content message translation",
  "subscription-required": "Subscription required translation",
  "translation":           "Translation format string",
  "unsupported-locale":    "Unsupported locale translation",
}

Testing Guidelines

Test Structure

  • Unit Tests: Located in test/ directory
  • Coverage Requirements: Maintained through Vitest
  • Locale Testing: Verify i18n functionality
  • Integration Testing: Test Discord interaction flows

Running Tests

Terminal window
# Run all tests with coverage
pnpm run test


# Run tests in watch mode (development)
npx vitest --watch


# Check test coverage
npx vitest run --coverage

Bug Reports and Feature Requests

Issue Templates

  • Bug Reports: Include steps to reproduce, expected vs actual behavior
  • Feature Requests: Describe use case, proposed implementation
  • Translation Issues: Specify locale and incorrect translation

Communication Channels

Release Process

Version Management

  • Semantic Versioning: Following semver conventions
  • Changelog: Maintained for all releases
  • Git Tags: Version tags for release tracking

Deployment Pipeline

  • Build Verification: All tests must pass
  • Linting Check: No linting errors allowed
  • Type Checking: TypeScript compilation must succeed
  • Manual Testing: Discord integration verification

Documentation Standards

Code Documentation

  • JSDoc: All public functions and complex logic
  • README: Project overview and quick start guide
  • CONTRIBUTING: Detailed contribution guidelines
  • This Document: Comprehensive application documentation

Maintenance

  • Regular Updates: Documentation updated with code changes
  • Accuracy: All examples and instructions verified
  • Accessibility: Clear language and structured formatting