---
title: 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](https://discord.com/oauth2/authorise?client_id=1338596130207957035) using the provided authorisation 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
```bash
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

## 3. Legal Documentation

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

### Licensing

Aria Iuvo is licensed under Naomi's Public Licence, as referenced in the global software licence documentation available at [docs.nhcarrigan.com](https://docs.nhcarrigan.com/#/license).

### 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

### Copyright and Attribution

- **Copyright Holder**: Naomi Carrigan (NHCarrigan)
- **Source Code**: Available at [git.nhcarrigan.com/NHCarrigan/aria-iuvo](https://git.nhcarrigan.com/NHCarrigan/aria-iuvo)
- **Attribution**: Uses LibreTranslate for translation services

## 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
```typescript
[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
```bash
# 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 behaviour
- **Feature Requests**: Describe use case, proposed implementation
- **Translation Issues**: Specify locale and incorrect translation

#### Communication Channels
- **Issues**: GitHub/Git repository issue tracker
- **Support**: [chat.nhcarrigan.com](https://chat.nhcarrigan.com)
- **Email**: contact@nhcarrigan.com

### 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
