create-ui18n-app

{{PROJECT_NAME}}

{{DESCRIPTION}}

A modern, type-safe Node.js REST API with built-in internationalization powered by UI18n. This project provides a robust foundation for building multilingual APIs with comprehensive error handling, security features, and developer-friendly tooling.

🌍 Features

• 🌐 Full Internationalization: Support for {{SUPPORTED_LANGUAGES}} languages with automatic detection
• ⚡ High Performance: Built-in caching and optimized translation workflows
• 🛡️ Security First: Helmet, CORS, rate limiting, and input validation
• 📝 TypeScript: Full type safety and excellent developer experience
• 🔧 Developer Friendly: Hot reload, comprehensive logging, and clear error messages
• 📚 RESTful API: Clean, consistent API design following REST principles
• 🧪 Production Ready: Comprehensive error handling and graceful degradation

🚀 Quick Start

Prerequisites

• Node.js >= 18.0.0
• npm >= 8.0.0

Installation

# Install dependencies
npm install

# Copy environment configuration
cp .env.example .env

# Build the project
npm run build

# Start development server
npm run dev

The API will be available at http://localhost:3000

Production Deployment

# Build for production
npm run build

# Start production server
npm start

📚 API Endpoints

Core Endpoints

• GET /health - Health check and system status
• GET /api - API documentation and information

Translation Endpoints

• GET /api/translate/:text - Simple translation to current language
• GET /api/translate/:text/:target - Translate to specific target language
• POST /api/translate - Advanced translation with options
• GET /api/languages - Get supported languages
• GET /api/status - Get API status and statistics

Language Management

• GET /api/language - Get current language information
• POST /api/language - Switch current language
• POST /api/detect - Detect language from text
• GET /api/stats - Get translation statistics

🛠️ Usage Examples

Simple Translation

# Translate to current language (auto-detected from headers)
curl "http://localhost:3000/api/translate/Hello World"

# Translate to specific language
curl "http://localhost:3000/api/translate/Hello World/zh"

Advanced Translation

curl -X POST http://localhost:3000/api/translate \\
  -H "Content-Type: application/json" \\
  -H "Accept-Language: zh-CN" \\
  -d '{
    "text": "Welcome to our API",
    "target_language": "zh",
    "context": "greeting",
    "format": "text"
  }'

Language Detection

curl -X POST http://localhost:3000/api/detect \\
  -H "Content-Type: application/json" \\
  -d '{
    "text": "こんにちは世界"
  }'

Switch Language

curl -X POST http://localhost:3000/api/language \\
  -H "Content-Type: application/json" \\
  -d '{
    "language": "zh"
  }'

🌐 Internationalization

Supported Languages

{{#each SUPPORTED_LANGUAGES}}

• {{this}}: {{#switch this}}{{#case 'en'}}English 🇺🇸{{/case}}{{#case 'zh'}}中文 🇨🇳{{/case}}{{#case 'es'}}Español 🇪🇸{{/case}}{{#case 'fr'}}Français 🇫🇷{{/case}}{{#case 'de'}}Deutsch 🇩🇪{{/case}}{{#case 'ja'}}日本語 🇯🇵{{/case}}{{#case 'ko'}}한국어 🇰🇷{{/case}}{{/switch}} {{/each}}

Language Detection

The API automatically detects the preferred language from:

• Query Parameter: ?lang=zh
• Custom Header: X-Language: zh
• Accept-Language Header: Accept-Language: zh-CN,zh;q=0.9,en;q=0.8
• User-Agent Hints: Browser/mobile client indicators
• Default Language: Falls back to {{DEFAULT_LANGUAGE}}

Adding New Languages

• Add translation files to locales/[language].json
• Update the supportedLanguages array in src/middleware/i18n.ts
• Add language information to utility functions

📁 Project Structure

{{PROJECT_NAME}}/
├── src/
│   ├── index.ts              # Application entry point
│   ├── app.ts                # Express app configuration
│   ├── middleware/
│   │   ├── i18n.ts           # Internationalization middleware
│   │   └── error.ts          # Error handling middleware
│   ├── routes/
│   │   ├── api.ts            # Main API routes
│   │   └── i18n.ts           # Language management routes
│   └── utils/
│       └── translation.ts    # Translation utilities
├── locales/                  # Translation files
│   ├── en.json              # English translations
│   └── zh.json              # Chinese translations
├── dist/                     # Built JavaScript files
├── .env.example             # Environment configuration template
├── package.json             # Dependencies and scripts
├── tsconfig.json            # TypeScript configuration
└── README.md               # This file

🔧 Configuration

Environment Variables

Copy .env.example to .env and configure:

# Server Configuration
PORT=3000
NODE_ENV=development

# UI18n Configuration
UI18N_DEFAULT_LANGUAGE={{DEFAULT_LANGUAGE}}
UI18N_CACHE_ENABLED={{ENABLE_CACHING}}

# Security Configuration
CORS_ORIGIN=*
RATE_LIMIT_MAX_REQUESTS=100

UI18n Configuration

The UI18n instance is configured with:

• Default Language: {{DEFAULT_LANGUAGE}}
• Caching: {{#if ENABLE_CACHING}}Enabled{{else}}Disabled{{/if}}
• Auto Detection: {{#if ENABLE_AUTO_DETECTION}}Enabled{{else}}Disabled{{/if}}
• Persistence: {{#if ENABLE_PERSISTENCE}}Enabled{{else}}Disabled{{/if}}

🧪 Development

Available Scripts

• npm run dev - Start development server with hot reload
• npm run build - Build for production
• npm run build:watch - Build with watch mode
• npm start - Start production server
• npm run type-check - Run TypeScript type checking
• npm run lint - Run ESLint
• npm run lint:fix - Fix ESLint issues
• npm run clean - Clean build artifacts

Development Tools

• Hot Reload: Automatic server restart on file changes
• TypeScript: Full type safety and IntelliSense
• ESLint: Code quality and consistency
• Request Logging: Detailed request/response logging in development

🛡️ Security Features

• Helmet: Security headers and protection
• CORS: Configurable cross-origin resource sharing
• Rate Limiting: Request rate limiting per IP
• Input Validation: Comprehensive request validation
• Error Sanitization: Safe error messages in production
• XSS Protection: Input sanitization and output escaping

📊 Monitoring

Health Check

The /health endpoint provides comprehensive system information:

• Service status and uptime
• Memory usage and performance metrics
• UI18n configuration and statistics
• Supported languages and current settings

Translation Statistics

Access /api/stats to get:

• Cache hit/miss ratios
• Translation counts and performance
• Language usage statistics
• System resource usage

🚀 Production Deployment

Build Optimization

• TypeScript Compilation: Optimized JavaScript output
• Tree Shaking: Remove unused code
• Minification: Compressed for smaller bundle size
• Source Maps: Debugging support in production

Deployment Checklist

• Set NODE_ENV=production
• Configure proper CORS_ORIGIN
• Set up appropriate rate limiting
• Configure logging and monitoring
• Set up health check endpoints
• Configure reverse proxy (nginx/Apache)
• Set up SSL/TLS certificates
• Configure database connections (if applicable)

Docker Support

FROM node:18-alpine

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

COPY dist ./dist
COPY locales ./locales

EXPOSE 3000
CMD ["npm", "start"]

🤝 Contributing

• Fork the repository
• Create a feature branch: git checkout -b feature-name
• Make your changes and add tests
• Commit your changes: git commit -am 'Add new feature'
• Push to the branch: git push origin feature-name
• Submit a pull request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• UI18n - Modern internationalization solution
• Express.js - Fast, unopinionated web framework
• TypeScript - Type-safe JavaScript development

📞 Support

• 📧 Issues: GitHub Issues
• 📚 Documentation: UI18n Docs
• 💬 Discussions: GitHub Discussions

Made with ❤️ using UI18n and create-ui18n-app