https://github.com/necordjs/localization

🌍 Localize your Discord bot with Necord!
https://github.com/necordjs/localization

bot discord i18n localization necord nestjs

Last synced: 10 months ago
JSON representation

🌍 Localize your Discord bot with Necord!

• Host: GitHub
• URL: https://github.com/necordjs/localization
• Owner: necordjs
• License: mit
• Created: 2024-04-05T06:54:01.000Z (almost 2 years ago)
• Default Branch: master
• Last Pushed: 2024-10-28T14:51:38.000Z (about 1 year ago)
• Last Synced: 2024-10-29T14:22:01.815Z (about 1 year ago)
• Topics: bot, discord, i18n, localization, necord, nestjs
• Language: TypeScript
• Homepage: https://necord.org/recipes/localization
• Size: 1.92 MB
• Stars: 11
• Watchers: 0
• Forks: 1
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Funding: .github/FUNDING.yml
  • License: LICENSE
  • Code of conduct: .github/CODE_OF_CONDUCT.md
  • Codeowners: .github/CODEOWNERS
  • Security: .github/SECURITY.md

Awesome Lists containing this project

README

          


   


       

   

  🌍 A lightweight Localization module for Necord

   



   Documentation ✨   Source code 🪡   Examples 🛠️   Community 💬








    

    

    

    



## About

`@necord/localization` is a lightweight localization module for [Necord](https://necord.org/). It allows you to easily localize your bot's

commands and messages. The module provides a simple API for managing locales and translations, as well as a powerful localization adapter

system.

## Installation

**Node.js 18.0.0 or newer is required.**

```bash

$ npm i @necord/localization necord discord.js

$ yarn add @necord/localization necord discord.js

$ pnpm add @necord/localization necord discord.js

```

## Usage

Once the installation process is complete, we can import the `NecordLocalizationModule` with your `NecordModule` into the

root `AppModule`:

```typescript

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

})

class AppModule {

}

```

Also, you can create your own localization adapter. Just implement the `LocalizationAdapter` interface:

```typescript

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

interface CustomLocalizationOptions {

    fallbackLocale: string;

    locales: Record>;

}

export class CustomLocalizationAdapter extends BaseLocalizationAdapter {

    public getTranslation(key: string, locale: string, ...args: any[]): string {

        return `${key} by ${locale}`;

    }

}

```

Then, we can inject the `LOCALIZATION_ADAPTER` into our service and use it to localize our commands and messages:

```typescript

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.description')

    })

    public ping(

        @Context() [interaction]: SlashCommandContext,

        @CurrentTranslate() t: TranslationFn

    ) {

        const message = t('commands.ping.description');

        return interaction.reply(message);

    }

}

```

Or you can use `@CurrentTranslate` decorator to get the current translation from context:

```typescript

import { Injectable, Inject, OnModuleInit } from '@nestjs/common';

import { DefaultLocalizationAdapter, CurrentTranslate, TranslationFn, localizationMapByKey } 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.description')

    })

    public ping(

        @Context() [interaction]: SlashCommandContext,

        @CurrentTranslate() t: TranslationFn

    ) {

        const message = t('commands.ping.description');

        return interaction.reply(message);

    }

}

```

Congratulations! You have successfully created your first localized command with Necord!

## Backers



## Stay in touch

* Author - [Alexey Filippov](https://t.me/socketsomeone)

* Twitter - [@SocketSomeone](https://twitter.com/SocketSomeone)

## License

[MIT](https://github.com/necordjs/necord/blob/master/LICENSE) © [Alexey Filippov](https://github.com/SocketSomeone)