CS2-SimpleAdmin/Modules/TRANSLATION_EXAMPLE.md

Module Translation Guide

🎓 New to translations? This guide shows you how to add multi-language support to your module!

Why Use Module Translations?

When you use SimpleAdmin API's translation system, each player automatically sees messages in their preferred language!

Example:

• 🇬🇧 Player with English: "Admin gave PlayerName a weapon!"
• 🇵🇱 Player with Polish: "Admin dał PlayerName broń!"
• 🇷🇺 Player with Russian: "Admin дал PlayerName оружие!"

All from ONE line of code!

Quick Start

Step 1: Create Your Translation Files

Create a lang folder in your module with translation files for each language:

YourModule/
└── lang/
    ├── en.json
    ├── pl.json
    └── ru.json

Example: lang/en.json

{
  "yourmod_admin_action": "{lightred}{0}{default} performed action on {lightred}{1}{default}!"
}

Example: lang/pl.json

{
  "yourmod_admin_action": "{lightred}{0}{default} wykonał akcję na {lightred}{1}{default}!"
}

Step 2: Use in Your Code

✅ RECOMMENDED METHOD: ShowAdminActivityLocalized

// Show activity with per-player language support
var args = new object[] { "CALLER", targetPlayer.PlayerName };
if (admin == null || !_api.IsAdminSilent(admin))
{
    if (Localizer != null)
    {
        // Each player sees this in their language!
        _api.ShowAdminActivityLocalized(
            Localizer,                         // Your module's localizer
            "yourmod_admin_action",            // Translation key
            admin.PlayerName,                  // Caller name
            false,                             // dontPublish
            args);                             // Message arguments
    }
}

That's it! SimpleAdmin handles the rest.

Complete Example

using CounterStrikeSharp.API.Core;
using CS2_SimpleAdminApi;

public partial class MyModule : BasePlugin
{
    private ICS2_SimpleAdminApi? _api;

    private void GiveWeaponToPlayer(CCSPlayerController admin, CCSPlayerController target, string weaponName)
    {
        // Give the weapon
        target.GiveNamedItem(weaponName);

        var callerName = admin.PlayerName;

        // Show activity using module's localizer - each player sees it in their language!
        if (admin == null || !_api!.IsAdminSilent(admin))
        {
            var args = new object[] { "CALLER", target.PlayerName, weaponName };
            if (Localizer != null)
            {
                _api!.ShowAdminActivityLocalized(Localizer, "yourmod_admin_give_message", callerName, false, args);
            }
        }

        // Log the command
        _api!.LogCommand(admin, $"css_give {target.PlayerName} {weaponName}");
    }
}

🔑 Important: The "CALLER" Placeholder

Always use "CALLER" as the first argument in your translation messages!

The API automatically replaces "CALLER" based on the server's ShowActivityType configuration:

ShowActivityType	What Players See
1	Non-admins see "Admin", admins see real name
2+	Everyone sees real admin name

Example:

{
  "yourmod_message": "{0} did something to {1}"
                     ↑ This will be replaced with "Admin" or admin's name
}

var args = new object[] { "CALLER", targetPlayer.PlayerName };
//                         ↑ API replaces this automatically

💡 Pro Tips

Tip 1: Use a Helper Method

Create a reusable helper to reduce code duplication:

/// <summary>
/// Helper method to show activity and log command
/// Copy this to your module!
/// </summary>
private void LogAndShowActivity(
    CCSPlayerController? caller,
    CCSPlayerController target,
    string translationKey,
    string baseCommand,
    params string[] extraArgs)
{
    var callerName = caller?.PlayerName ?? "Console";

    // Build args: "CALLER" + target name + any extra args
    var args = new List<object> { "CALLER", target.PlayerName };
    args.AddRange(extraArgs);

    // Show activity with per-player language support
    if (caller == null || !_api.IsAdminSilent(caller))
    {
        if (Localizer != null)
        {
            _api.ShowAdminActivityLocalized(
                Localizer,
                translationKey,
                callerName,
                false,
                args.ToArray());
        }
    }

    // Build and log command
    var logCommand = $"{baseCommand} {target.PlayerName}";
    if (extraArgs.Length > 0)
    {
        logCommand += $" {string.Join(" ", extraArgs)}";
    }
    _api.LogCommand(caller, logCommand);
}

Usage:

// Simple action
LogAndShowActivity(admin, target, "yourmod_kick_message", "css_kick");

// Action with parameters
LogAndShowActivity(admin, target, "yourmod_hp_message", "css_hp", "100");

Tip 2: Translation Key Naming Convention

Use a consistent prefix for your module:

{
  "yourmod_admin_action1": "...",
  "yourmod_admin_action2": "...",
  "yourmod_error_notarget": "..."
}

This prevents conflicts with other modules and makes it clear which module owns the translation.

Tip 3: Color Formatting

Use CounterStrikeSharp color tags in your translations:

{
  "yourmod_message": "{lightred}{0}{default} gave {green}{1}{default} a {yellow}{2}{default}!"
}

Available colors:

• {default}, {white}, {darkred}, {green}, {lightyellow}
• {lightblue}, {olive}, {lime}, {red}, {purple}
• {grey}, {yellow}, {gold}, {silver}, {blue}
• {darkblue}, {bluegrey}, {magenta}, {lightred}, {orange}

📖 Real Example: Fun Commands Module

The CS2-SimpleAdmin_FunCommands module is a perfect reference:

Translation files: Modules/CS2-SimpleAdmin_FunCommands/lang/

• Has 13 languages (en, pl, ru, de, fr, es, etc.)
• Shows proper key naming (fun_admin_*)
• Demonstrates color usage

Code examples: Modules/CS2-SimpleAdmin_FunCommands/CS2-SimpleAdmin_FunCommands/Actions.cs

• Lines 20-31: God mode with translations
• Lines 48-59: NoClip with translations
• Lines 76-86: Freeze with translations

Helper method: Modules/CS2-SimpleAdmin_FunCommands/CS2-SimpleAdmin_FunCommands/Commands.cs:274-306

❌ Common Mistakes

Mistake 1: Forgetting "CALLER"

// ❌ WRONG
var args = new object[] { admin.PlayerName, target.PlayerName };

// ✅ CORRECT
var args = new object[] { "CALLER", target.PlayerName };

Mistake 2: Using SimpleAdmin's Translations

// ❌ WRONG - Uses SimpleAdmin's keys
_api.ShowAdminActivity("sa_admin_kick", ...)

// ✅ CORRECT - Uses YOUR module's keys
_api.ShowAdminActivityLocalized(Localizer, "yourmod_kick", ...)

Mistake 3: Not Checking Localizer

// ❌ WRONG - Will crash if Localizer is null
_api.ShowAdminActivityLocalized(Localizer, "key", ...)

// ✅ CORRECT - Check first
if (Localizer != null)
{
    _api.ShowAdminActivityLocalized(Localizer, "key", ...)
}

🔗 See Also

• MODULE_DEVELOPMENT.md - Complete module development guide
• CS2-SimpleAdmin_FunCommands/README.md - Reference implementation
• CounterStrikeSharp Localization - Official CSS localization docs

---

Need help? Study the FunCommands module - it demonstrates all these patterns correctly!