Localização

@necord/localization é um módulo de localização leve para Necord. Ele permite que você localize facilmente os comandos do seu bot. O módulo fornece uma API simples para gerenciamento de localizações e traduções, bem como um poderoso sistema de adaptador de localização.

Instalação

npm

npm i @necord/localization necord discord.js

Yarn

yarn add @necord/localization necord discord.js

pnpm

pnpm add @necord/localization necord discord.js

Utilização

Uma vez que o processo de instalação estiver concluído, nós podemos importar o NecordLocalizationModule com o seu NecordModule para a raiz AppModule:

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,
            // Você também pode prover uma classe com suporte a injeções com @Inject
            adapter: new DefaultLocalizationAdapter({
                fallbackLocale: 'en-US',
                locales: {
                    'en-US': {
                        'commands.ping.name': 'ping',
                        'commands.ping.description': 'Pong!'
                    },
                    pt-BR: {
                        'commands.ping.name': 'ping',
                        'commands.ping.description': 'Pong!'
                    }
                }
            })
        })
    ],
    providers: [AppService]
})
export class AppModule {
}

Adaptadores

O DefaultLocalizationAdapter é um adaptador simples que permite que você forneça um mapa de locais e traduções.

Também você pode usar o NestedLocalizationAdapter que lhe permite organizar chaves de tradução em objetos

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': 'ping',
                                'description': 'Pong!'
                            }
                        }
                    }
                }
            })
        })
    ],
    providers: [AppService]
})
export class AppModule {
}

info

DefaultLocalizationAdapter e NestedLocalizationAdapter podem traduzir seus textosde localização e espaços reservados (por exemplo, {{username}})

Adaptadores Personalizados

Além disso, você pode criar seu próprio adaptador de localização. Basta implementar a interface do 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} por ${locale}`;
    }
}

Resolvedores

Resolutores são usados para obter a localidade para tradução. Por padrão, Necord fornece dois resolventes: UserResolver e GuildResolver.

Resolvedor	Descrição
UserResolver	Obtém a localidade da propriedade local do usuário (interaction.locale)
GuildResolver	Obtém a localidade da propriedade local do servidor (interaction.guildLocale)

Resolvedores Personalizados

Além disso, você pode criar seu próprio Resolvedor. Basta implementar a 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;
    }
}

Localização

Podemos injetar o LOCALIZATION_ADAPTER no nosso serviço e usá-lo para localizar nossos comandos e mensagens:

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 você pode usar o decorador @CurrentTranslate para obter a tradução atual do contexto:

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

A função localizationMapByKey é usada para localizar o nome e a descrição do comando. Você passa a chave de tradução ou mapa de localização como um argumento para a função.

Configurando comandos localizados

Você pode definir quais localidades o comando será localizado

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

Ou passe um objeto de localização com a chave de localização e tradução para nameLocalization e descriptionLocalizations propriedades

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

Parabéns! Você criou com sucesso seu primeiro comando localizado com Necord!

Você pode ver um exemplo funcional aqui.