Is there a way to localize Swagger api endpoints in Nestjs?

2 min read 22-09-2024

Is there a way to localize Swagger api endpoints in Nestjs?

NestJS is a powerful framework for building server-side applications using Node.js, and it seamlessly integrates with Swagger to provide interactive API documentation. However, if you are looking to serve your API documentation in multiple languages, you may wonder, "Is there a way to localize Swagger API endpoints in NestJS?" Let's explore this question in detail, provide an example, and offer some practical tips.

Understanding the Problem

Localization in APIs often involves adapting the documentation and the endpoints to cater to different languages or regional standards. While NestJS's integration with Swagger is straightforward, customizing the Swagger UI to support multiple languages requires additional configuration.

Original Code for Swagger Setup in NestJS

Here’s a typical setup for Swagger in a NestJS application:

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  
  const options = new DocumentBuilder()
    .setTitle('Example API')
    .setDescription('API description in English')
    .setVersion('1.0')
    .build();
  
  const document = SwaggerModule.createDocument(app, options);
  SwaggerModule.setup('api', app, document);
  
  await app.listen(3000);
}

bootstrap();

Localizing Swagger API Endpoints

To localize the Swagger API endpoints in NestJS, you would typically follow these steps:

Internationalization (i18n) Module: Utilize an internationalization library like nestjs-i18n to manage translations. This allows you to maintain a dictionary of translations for your API documentation.
Dynamic Documentation Generation: Modify the Swagger setup to dynamically pull the appropriate translations based on user preferences or request parameters.

Example Code

Here's how you could refactor the original Swagger setup to allow for localization:

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { I18nService } from 'nestjs-i18n';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  const i18nService = app.get(I18nService);
  
  const options = new DocumentBuilder()
    .setTitle(i18nService.t('swagger.title')) // dynamic title based on locale
    .setDescription(i18nService.t('swagger.description')) // dynamic description
    .setVersion('1.0')
    .build();
  
  const document = SwaggerModule.createDocument(app, options);
  SwaggerModule.setup('api', app, document);
  
  await app.listen(3000);
}

bootstrap();

Key Takeaways and Best Practices

Maintain a Translation File: Create a separate file (JSON or YAML) for each language with the respective translations. This file will contain the keys used in the setTitle() and setDescription() methods, allowing you to switch easily between languages.
Dynamic Language Detection: Implement middleware to detect the user's preferred language, whether from headers, cookies, or query parameters, and then serve the appropriate localized documentation.
User-Friendly Documentation: Make sure that the localized Swagger documentation maintains usability and readability, ensuring that endpoints are clearly defined regardless of language.

Conclusion

Localizing Swagger API endpoints in NestJS involves leveraging internationalization libraries to dynamically generate documentation based on the user’s language preferences. By following the outlined approach and best practices, you can enhance the user experience for clients from diverse linguistic backgrounds.

Useful Resources

By implementing the above strategies, you can create an inclusive API that resonates with a global audience, thus improving engagement and usability.