Localisation

@necord/localization est un module de localisation léger pour Necord. Il vous permet de localiser facilement les commandes et messages de votre bot. Le module fournit une API simple pour gérer les locales et les traductions, ainsi qu'un puissant système d'adaptateur de localisation.

Installation

npm

npm i @necord/localization necord discord.js

Yarn

yarn add @necord/localization necord discord.js

pnpm

pnpm add @necord/localization necord discord.js

Bun

bun add @necord/localization necord discord.js

Utilisation

Une fois le processus d'installation terminé, nous pouvons importer le NecordLocalizationModule avec votre NecordModule dans le AppModule racine :

import { NecordModule } from 'necord';
import { Module } from '@nestjs/common';
import { NecordLocalizationModule, DefaultLocalizationAdapter, UserResolver } from '@necord/localization';
import { AppService } from './app.service';

@Module({
    imports: [
        NecordModule.forRoot({
            token: process.env.DISCORD_TOKEN,
            intents: [
                IntentsBitField.Flags.Guilds,
                IntentsBitField.Flags.DirectMessages,
                IntentsBitField.Flags.GuildMembers,
                IntentsBitField.Flags.GuildMessages,
                IntentsBitField.Flags.MessageContent
            ],
            prefix: '!',
            development: [process.env.DISCORD_TEST_GUILD]
        }),
        NecordLocalizationModule.forRoot({
            resolvers: UserResolver,
            // Also you can provide class for support injection by @Inject
            adapter: new DefaultLocalizationAdapter({
                fallbackLocale: 'en-US',
                locales: {
                    'en-US': {
                        'commands.ping.name': 'ping',
                        'commands.ping.description': 'Pong!'
                    },
                    ru: {
                        'commands.ping.name': 'пинг',
                        'commands.ping.description': 'Понг!'
                    }
                }
            })
        })
    ],
    providers: [AppService]
})
export class AppModule {
}

Adaptateurs

Le DefaultLocalizationAdapter est un adaptateur simple qui vous permet de fournir une carte des locales et des traductions.

Vous pouvez aussi utiliser le NestedLocalizationAdapter qui vous permet d'organiser les clés de traduction dans des objets

import { NecordModule } from 'necord';
import { Module } from '@nestjs/common';
import { NecordLocalizationModule, NestedLocalizationAdapter, UserResolver } from '@necord/localization';
import { AppService } from './app.service';

@Module({
    imports: [
        NecordModule.forRoot({
            token: process.env.DISCORD_TOKEN,
            intents: [
                IntentsBitField.Flags.Guilds,
                IntentsBitField.Flags.DirectMessages,
                IntentsBitField.Flags.GuildMembers,
                IntentsBitField.Flags.GuildMessages,
                IntentsBitField.Flags.MessageContent
            ],
            prefix: '!',
            development: [process.env.DISCORD_TEST_GUILD]
        }),
        NecordLocalizationModule.forRoot({
            resolvers: UserResolver,
            adapter: new NestedLocalizationAdapter({
                fallbackLocale: 'en-US',
                locales: {
                    'en-US': {
                        'commands': {
                            'ping': {
                                'name': 'ping',
                                'description': 'Pong!'
                            }
                        }
                    },
                    ru: {
                        'commands': {
                            'ping': {
                                'name': 'пинг',
                                'description': 'Понг!'
                            }
                        }
                    }
                }
            })
        })
    ],
    providers: [AppService]
})
export class AppModule {
}

info

DefaultLocalizationAdapter et NestedLocalizationAdapter peuvent traduire vos chaînes de localisation et vos placeholders (par ex. {{username}})

Adaptateurs personnalisés

Vous pouvez aussi créer votre propre adaptateur de localisation. Implémentez simplement l'interface BaseLocalizationAdapter :

import { BaseLocalizationAdapter } from '@necord/localization';

interface CustomLocalizationOptions {
    fallbackLocale: string;
    locales: Record<string, Record<string, string>>;
}

export class CustomLocalizationAdapter extends BaseLocalizationAdapter<CustomLocalizationOptions> {
    public getTranslation(key: string, locale: string, ...args: any[]): string {
        return `${key} by ${locale}`;
    }
}

Resolvers

Les resolvers sont utilisés pour obtenir la locale pour la traduction. Par défaut, Necord fournit deux resolvers : UserResolver et GuildResolver.

Resolver	Description
UserResolver	Obtient la locale à partir de la propriété de locale de l'utilisateur (interaction.locale)
GuildResolver	Obtient la locale à partir de la propriété de locale du serveur (interaction.guildLocale)

Resolvers personnalisés

Vous pouvez aussi créer votre propre Resolver. Implémentez simplement l'interface LocaleResolver :

import { CommandContext, LocaleResolver } from '@necord/localization';
import { ExecutionContext, Injectable } from '@nestjs/common';
import { NecordExecutionContext } from 'necord';

@Injectable()
export class GuildResolver implements LocaleResolver {
    resolve(context: ExecutionContext): string | string[] | undefined {
        const necordContext = NecordExecutionContext.create(context);
        const [interaction] = necordContext.getContext<CommandContext>();

        return interaction.guildLocale;
    }
}

Localisation

Nous pouvons injecter le LOCALIZATION_ADAPTER dans notre service et l'utiliser pour localiser nos commandes et messages :

import { Injectable, Inject, OnModuleInit } from '@nestjs/common';
import { DefaultLocalizationAdapter, localizationMapByKey, LOCALIZATION_ADAPTER } from '@necord/localization';
import { Context, SlashCommand, SlashCommandContext } from 'necord';

@Injectable()
export class AppService implements OnModuleInit {
    public constructor(
        @Inject(LOCALIZATION_ADAPTER)
        private readonly localizationAdapter: DefaultLocalizationAdapter
    ) {
    }

    @SlashCommand({
        name: 'ping',
        description: 'Pong!',
        nameLocalizations: localizationMapByKey('commands.ping.name'),
        descriptionLocalizations: localizationMapByKey('commands.ping.name')
    })
    public ping(@Context() [interaction]: SlashCommandContext) {
        const message = this.localizationAdapter.getTranslation(
            'commands.ping.description',
            interaction.locale
        );
        return interaction.reply(message);
    }
}

Ou vous pouvez utiliser le décorateur @CurrentTranslate pour obtenir la traduction actuelle à partir du contexte :

import { Injectable, Inject, OnModuleInit } from '@nestjs/common';
import { DefaultLocalizationAdapter, CurrentTranslate, localizationMapByKey, TranslationFn } from '@necord/localization';
import { Context, SlashCommand, SlashCommandContext } from 'necord';

@Injectable()
export class AppService implements OnModuleInit {
    @SlashCommand({
        name: 'ping',
        description: 'Pong!',
        nameLocalizations: localizationMapByKey('commands.ping.name'),
        descriptionLocalizations: localizationMapByKey('commands.ping.name')
    })
    public ping(
        @Context() [interaction]: SlashCommandContext,
        @CurrentTranslate() t: TranslationFn
    ) {
        const message = t('commands.ping.description');
        return interaction.reply(message);
    }
}

info

La fonction localizationMapByKey est utilisée pour localiser le nom et la description de la commande. Vous passez la clé de traduction ou la carte de localisation comme argument à la fonction.

Configuration des commandes localisées

Vous pouvez définir dans quelles locales la commande sera localisée

@SlashCommand({
    name: 'ping',
    description: 'Pong!',
    nameLocalizations: localizationMapByKey('commands.ping.name', ['en', 'ru']),
    descriptionLocalizations: localizationMapByKey('commands.ping.name', ['en', 'ru'])
})

Ou passez simplement un objet de localisation avec l'identifiant de localisation et la clé de traduction aux propriétés nameLocalization et descriptionLocalizations

@SlashCommand({
    name: 'ping',
    description: 'Pong!',
    nameLocalizations: {
        en: 'command.ping.name',
        ru: 'command.ping.name'
    },
    descriptionLocalizations: {
        en: 'command.ping.description',
        ru: 'command.ping.description'
    }
})

Félicitations ! Vous avez créé avec succès votre première commande localisée avec Necord !

Vous pouvez consulter un exemple fonctionnel ici.