auth0-email-i18n

v1.0.2

Published

5 months ago

Simple and effective CLI tool for generating bilingual (EN/FR) email templates for Auth0 with Liquid template syntax

Downloads

0High
0Medium
0Low

lingelo

auth0 email i18n internationalization templates localization liquid cli generator multilingual

🚀 Auth0 Email i18n

Simple and effective CLI tool for generating bilingual (EN/FR) email templates for Auth0 with Liquid template syntax.

✨ Features

🌍 Bilingual support - English (US) and French (FR) out of the box
🔧 Simple CLI - Interactive commands for setup and generation
🔒 Secure - No eval() usage, proper input validation
📝 Liquid templates - Generates Auth0-compatible Liquid conditionals
⚡ TypeScript - Type-safe configuration and code
🧪 Tested - 55 tests covering core functionality

📦 Installation

From npm (when published)

# Install globally
npm install -g auth0-email-i18n

# Or use with npx
npx auth0-email-i18n init

For Development

# Clone the repository
git clone https://github.com/Lingelo/auth0-international-email.git
cd auth0-international-email

# Install dependencies
yarn install

# Build the project
yarn build

# Generate templates
yarn generate

🚀 Quick Start

# Build and generate templates
yarn generate

# Output will be in dist/output/

Your internationalized email templates will be generated with Liquid conditionals ready for Auth0.

📁 Project Structure

src/
├── cli/                    # CLI commands
│   ├── CliApp.ts          # Main CLI application
│   └── commands/          # Command implementations
├── core/
│   ├── interfaces/        # TypeScript interfaces
│   └── services/          # Core services (I18n, Template, Validation)
├── generators/            # Template generators
│   └── LiquidGenerator.ts # Liquid template generator
├── languages/             # Translation files
│   └── README.md         # Guide for creating translations
├── templates/             # Email templates
│   └── README.md         # Guide for creating templates
└── utils/                 # Utilities
    ├── ConfigLoader.ts    # Config validation
    ├── FileSystem.ts      # File operations
    ├── Logger.ts          # Logging
    └── templateEngine.ts  # Template processing

config.json                # Project configuration (empty by default)
dist/output/               # Generated templates (created on build)

🎯 Available Commands

Development Commands

yarn generate              # Build and generate templates
yarn build                 # Compile TypeScript
yarn test                  # Run tests
yarn lint                  # Check code style
yarn typecheck             # TypeScript validation

CLI Commands (after build)

node dist/main.js init              # Initialize project
node dist/main.js build             # Generate templates
node dist/main.js validate          # Validate config
node dist/main.js add-language      # Add new language

🌍 Getting Started with Languages

The library comes with no default language files - you create your own!

Step 1: Create Language Files

Create JSON files in src/languages/ for each language you want to support.

Example: src/languages/en-US.json

{
  "welcome": {
    "subject": "Welcome!",
    "title": "Welcome to our service",
    "content": "We're glad to have you."
  }
}

Example: src/languages/fr-FR.json

{
  "welcome": {
    "subject": "Bienvenue !",
    "title": "Bienvenue sur notre service",
    "content": "Nous sommes ravis de vous accueillir."
  }
}

See src/languages/README.md for detailed examples and best practices.

📧 Getting Started with Templates

The library comes with no default templates - you create your own!

Step 1: Create Template Files

Create HTML files in src/templates/ using ${localizeMessage("key")} for translatable content.

Example: src/templates/welcome_email.html

<!DOCTYPE html>
<html lang="en">
<head>
    <title>${localizeMessage("welcome.subject")}</title>
</head>
<body>
    <h1>${localizeMessage("welcome.title")}</h1>
    <p>${localizeMessage("welcome.content")}</p>
</body>
</html>

See src/templates/README.md for detailed examples and best practices.

Step 2: Register in config.json

{
  "templates": [
    {
      "name": "welcome_email",
      "from": "[email protected]",
      "subjectKey": "welcome.subject",
      "enabled": true
    }
  ]
}

Generated Output

The build process converts templates to Liquid conditionals for Auth0:

{% if user.user_metadata.language == 'fr-FR' %}Bienvenue
{% elsif user.user_metadata.language == 'en-US' %}Welcome
{% else %}Welcome{% endif %}

Output files in dist/output/:

{template-name}.html - Localized HTML with Liquid syntax
{template-name}.json - Auth0 configuration metadata

⚙️ Configuration

The default config.json is empty - a clean slate for your project:

{
  "name": "Auth0 Email i18n",
  "version": "1.0.0",
  "templates": [],
  "languages": [],
  "build": {
    "outputDir": "dist/output",
    "cleanOutput": true
  }
}

Adding Your Configuration

Step 1: Add Languages

{
  "languages": [
    {
      "code": "en-US",
      "name": "English (United States)",
      "enabled": true,
      "priority": 1,
      "fallback": null
    },
    {
      "code": "fr-FR",
      "name": "Français (France)",
      "enabled": true,
      "priority": 2,
      "fallback": "en-US"
    }
  ]
}

Step 2: Add Templates

{
  "templates": [
    {
      "name": "welcome_email",
      "from": "[email protected]",
      "subjectKey": "welcome.subject",
      "enabled": true
    }
  ]
}

Configuration Fields

templates: Array of template configurations
languages: Supported languages with priority and fallbacks
build.outputDir: Where generated files are placed
build.cleanOutput: Clean output directory before each build

🔧 Development

Code Quality

yarn lint              # ESLint + Prettier check
yarn lint:fix          # Auto-fix issues
yarn format            # Format with Prettier
yarn typecheck         # TypeScript validation

Testing

yarn test              # Run all tests (55 tests)
yarn test:watch        # Watch mode
yarn test:coverage     # Coverage report

Build Process

TypeScript compilation (tsc)
Copy language files to dist/languages/
Copy templates to dist/templates/
Generate output in dist/output/

🏗️ Architecture

Service-oriented - Core business logic in services
Command pattern - CLI commands are extensible
Factory pattern - Template generators
Type-safe - Full TypeScript coverage
Tested - Comprehensive test suite

Key Components

TemplateService - Template loading and processing
I18nService - Translation management with fallbacks
ValidationService - Config and template validation
LiquidGenerator - Converts templates to Liquid syntax
ConfigLoader - Type-safe configuration loading

🔒 Security

✅ No eval() usage - secure regex-based template processing
✅ Input validation - all user inputs validated
✅ Path sanitization - safe file operations
✅ Error handling - comprehensive error boundaries

📊 Project Status

Current Version: 1.0.0

What's Implemented:

✅ Bilingual template generation (EN/FR)
✅ Liquid syntax conversion
✅ Interactive CLI commands
✅ Config validation
✅ Comprehensive test suite
✅ TypeScript compilation
✅ Build system

Planned Features:

🔄 Plugin system for custom processors
🔄 Advanced caching strategies
🔄 Additional language support
🔄 Performance metrics collection
🔄 HTML minification

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes
Push to the branch
Open a Pull Request

🔗 Links

Repository: https://github.com/Lingelo/auth0-international-email
Issues: https://github.com/Lingelo/auth0-international-email/issues
Auth0 Documentation: https://auth0.com/docs

Made for Auth0 email internationalization 🌍