Greed i18n - Translation Guide

Tip

If you have any questions about translating or need help, you can join our Discord server for support: https://discord.gg/greed

Welcome to the Greed internationalization (i18n) repository! This guide will walk you through everything you need to know to contribute translations to Greed, a powerful Discord bot built with Discordeno.

Table of Contents

• Overview
• Getting Started
• Folder Structure
• Translation Basics
• File Structure
• Translation Guidelines
• Submitting Translations
• Supported Languages
• Common Issues

Overview

The Greed bot uses i18next for internationalization. All translation files are stored in JSON format within the locales directory. Each language has its own folder containing translations for commands, common messages, categories, and permissions.

Getting Started

Prerequisites

• A text editor (VS Code, Notepad++, or any JSON-compatible editor)
• Basic knowledge of JSON syntax
• Understanding of the language you're translating to

Quick Start

1. Choose a language you want to translate to (or improve existing translations)
2. Navigate to the locales folder and find your language code folder (e.g., en, de, ko)
3. Open the English (en) folder as your reference
4. Start translating! Copy the structure from English files and translate the values

Folder Structure

locales/
├── en/                    # English (base language - always complete)
│   ├── common.json       # Common messages (errors, success, etc.)
│   ├── categories.json   # Command category names
│   ├── permissions.json  # Permission names
│   └── commands/         # Command translations
│       ├── information/  # Information commands
│       ├── lastfm/       # LastFM commands
│       ├── security/     # Security commands
│       └── ...
├── de/                    # German
├── ko/                    # Korean
└── [other languages]/     # Other supported languages

Translation Basics

Language Codes

Use standard ISO 639-1 language codes:

• en - English
• de - German
• es - Spanish
• fr - French
• it - Italian
• pt - Portuguese
• ru - Russian
• ja - Japanese
• ko - Korean
• zh - Chinese

JSON Format

All translation files are JSON objects. Here's a basic example:

{
  "key": "Value in target language",
  "nested": {
    "key": "Nested value"
  }
}

Important:

• Always use double quotes (") for strings
• No trailing commas
• Ensure valid JSON syntax (use a JSON validator if unsure)

File Structure

1. common.json

Contains common messages used throughout the bot:

{
  "errors": {
    "missingPermissions": "You are missing **{{permissions}}** permission(s)",
    "generic": "An error occurred"
  },
  "success": "Success!",
  "pagination": {
    "cannotInteract": "You cannot **interact** with this **paginator**"
  }
}

2. categories.json

Command category names:

{
  "information": "Information",
  "developer": "Developer",
  "utility": "Utility"
}

3. permissions.json

Discord permission names (usually kept in English, but can be translated):

{
  "ADMINISTRATOR": "Administrator",
  "MANAGE_GUILD": "Manage Server"
}

4. Command Files

Commands are organized by category. For example, commands/lastfm/index.json:

{
  "description": "LastFM music tracking commands",
  "help": "Use `lastfm set (username)` to link your LastFM account.",
  "errors": {
    "unknownSubcommand": "Unknown subcommand: `{{subcommand}}`"
  }
}

Translation Guidelines

1. Keep Placeholders

Placeholders like {{variable}}, {{prefix}}, {{permissions}} must be kept exactly as they are. These are replaced by the bot at runtime.

✅ Correct:

"You are missing **{{permissions}}** permission(s)"

❌ Wrong:

"You are missing **{permissions}** permission(s)"
"You are missing **{{permission}}** permission(s)"

2. Preserve Markdown Formatting

Keep all markdown formatting intact:

• **bold** for bold text
• *italic* for italic text
• `code` for inline code
• ```code``` for code blocks

3. Preserve Discord Formatting

Keep Discord-specific formatting:

• <@userID> for user mentions
• <#channelID> for channel mentions
• <@&roleID> for role mentions

4. Context Matters

Read the context before translating. Some words might have specific meanings:

• "LastFM" is a service name - keep it as is or use the official name in your language
• Command names in backticks (`command`) should usually remain in English
• Technical terms can be kept in English if there's no good translation

5. Tone and Style

• Use a friendly but professional tone
• Match the style of the original English text
• Keep it concise but clear
• Avoid overly formal language (this is a Discord bot, not a corporate document)

6. File Names

Never change file or folder names! Only translate the content within JSON files.

Submitting Translations

Before Submitting

1. ✅ Validate your JSON files (use a JSON validator)
2. ✅ Check that all placeholders are preserved
3. ✅ Ensure markdown formatting is intact
4. ✅ Verify that your translations make sense in context
5. ✅ Test that file structure matches the English version

What to Translate

• ✅ All text values in JSON files
• ✅ Error messages
• ✅ Help text
• ✅ Descriptions
• ✅ Button labels (if present)

What NOT to Translate

• ❌ File names
• ❌ Folder names
• ❌ JSON keys (the left side of "key": "value")
• ❌ Placeholder variables ({{variable}})
• ❌ Command names in backticks (usually)
• ❌ URLs

Supported Languages

Currently supported languages:

• ✅ English (en) - Complete (base language)
• ✅ German (de) - Complete
• ✅ Korean (ko) - Complete
• 🔄 Spanish (es) - In progress
• 🔄 French (fr) - In progress
• 🔄 Italian (it) - In progress
• 🔄 Portuguese (pt) - In progress
• 🔄 Russian (ru) - In progress
• 🔄 Japanese (ja) - In progress
• 🔄 Chinese (zh) - In progress

Legend:

• ✅ Complete
• 🔄 In progress
• ❌ Not started

Common Issues

Issue: "Invalid JSON syntax"

Solution:

• Check for trailing commas
• Ensure all strings use double quotes
• Validate using an online JSON validator
• Check for missing closing braces/brackets

Issue: "Translation not showing"

Solution:

• Verify the file is in the correct location
• Check that the language code matches exactly (e.g., de, not DE or de-DE)
• Ensure the JSON keys match the English version exactly
• Check that placeholders are preserved correctly

Issue: "Placeholder not working"

Solution:

• Ensure placeholders use double curly braces: {{variable}}
• Don't translate placeholder names (e.g., {{permissions}} stays as is)
• Check for typos in placeholder names

Issue: "Markdown not formatting"

Solution:

• Ensure markdown syntax is preserved exactly
• Check that asterisks are not escaped
• Verify backticks are used correctly

Best Practices

1. Start with common.json - This file contains the most frequently used messages
2. Translate category by category - Focus on one command category at a time
3. Reference the English version - Always keep the English version open as reference
4. Test your translations - If possible, test translations in the bot to see how they appear
5. Be consistent - Use the same terminology throughout your translations
6. Ask for help - If unsure about a translation, ask in the Discord server

File Organization Example

Here's how a complete translation for a command might look:

English (en/commands/lastfm/index.json):

{
  "description": "LastFM music tracking commands",
  "help": "Use `lastfm set (username)` to link your LastFM account.",
  "changeAccount": "If you want to change your account, run `{{prefix}}lastfm set`",
  "errors": {
    "unknownSubcommand": "Unknown subcommand: `{{subcommand}}`"
  }
}

German (de/commands/lastfm/index.json):

{
  "description": "LastFM-Musik-Tracking-Befehle",
  "help": "Verwende `lastfm set (username)`, um dein LastFM-Konto zu verknüpfen.",
  "changeAccount": "Wenn du dein Konto ändern möchtest, führe `{{prefix}}lastfm set` aus",
  "errors": {
    "unknownSubcommand": "Unbekannter Unterbefehl: `{{subcommand}}`"
  }
}

Notice:

• Keys remain the same
• Placeholders ({{prefix}}, {{subcommand}}) are preserved
• Markdown formatting ( backticks ) is preserved
• Only the values are translated

Additional Resources

• i18next Documentation
• ISO 639-1 Language Codes
• JSON Validator

License

This translation work is licensed under the same license as the main Greed project. See LICENSE for details.

Code of Conduct

Please read and follow our Code of Conduct when contributing translations.

---

Thank you for contributing to Greed's internationalization! 🌍

Your translations help make Greed accessible to users around the world. Every contribution, no matter how small, is appreciated!