langie

Langie API SDK

Lightweight translation SDK for Vue.js, Nuxt.js, and vanilla JavaScript applications with smart interface language selection and limit monitoring.

🚀 Live Demo

Requirements

• Node.js 18.0.0 or higher
• Vue 3.2.0 or higher
• Nuxt 3.0.0 or higher (optional)
• Modern browser with ES2020+ support

Installation

npm install langie

Dependencies

The SDK uses the following external libraries:

• countries-and-timezones - For accurate timezone to country mapping (316KB, MIT license)
• @vueform/multiselect - For the language selection dropdown component

Quick Start

Basic Usage

<script setup>
import { useLangie } from 'langie'
import { lt } from 'langie/components'

const { lr, setLanguage } = useLangie()
</script>

<template>
  <h1>{{ lr('Welcome to our application') }}</h1>
  <lt>Hello world!</lt>
  <button @click="setLanguage('es')">Switch to Spanish</button>
</template>

Global Component Registration

You can register the lt component globally for easier usage throughout your application:

// main.js
import { createApp } from 'vue'
import App from './App.vue'
import { lt } from 'langie/components'

const app = createApp(App)

// Register lt component globally
app.component('lt', lt)

app.mount('#app')

Then use it directly in templates without importing:

<template>
  <div>
    <h1><lt>Welcome to our application!</lt></h1>
    <p><lt>This text will be translated automatically.</lt></p>
    <button><lt>Click me</lt></button>
  </div>
</template>

<script setup>
import { useLangie } from 'langie'

const { setLanguage } = useLangie()
</script>

Documentation

• Getting Started - Installation and basic setup
• Vue.js Usage - Vue composables, components, and best practices
• Components - Ready-to-use Vue components
• Composables - Vue composables and reactive state
• Advanced Usage - Complex patterns and optimization
• TypeScript Support - TypeScript integration guide
• Nuxt.js Integration - SSR support, plugins, and deployment
• JavaScript Usage - Vanilla JS, React, and Node.js integration
• Core API - Core translation functions
• Backend Integration - API requirements and setup
• Contributing - Development and contribution guidelines
• Compatibility Guide - Version requirements and compatibility

Required CSS

For LanguageSelect component:

// main.js
import '@vueform/multiselect/themes/default.css'
import 'langie/dist/index.css'

Advanced Usage

Global Translation Defaults

You can set global defaults for all translation functions and the lt component to avoid repeating common parameters:

// main.js
import { createApp } from 'vue'
import App from './App.vue'
import { lt, setLtDefaults } from 'langie/components'

const app = createApp(App)

// Register lt component globally
app.component('lt', lt)

// Set global defaults (optional)
setLtDefaults({
  ctx: 'ui', // default context
  orig: 'en' // optional original language (no default)
})

app.mount('#app')

Now you can use simplified syntax:

<template>
  <!-- Uses global defaults: ctx="ui" -->
  <lt>Cancel</lt>

  <!-- Override specific props -->
  <lt ctx="content">Article title</lt>
  <lt orig="fr">Bonjour</lt>

  <!-- Both overrides -->
  <lt ctx="content" orig="es">Hola mundo</lt>
</template>

// Functions also use global defaults
const { l, lr } = useLangie()

// Uses global defaults: ctx="ui"
l('Hello world') // Not reactive, for JS only
lr('Welcome message') // Reactive, for Vue templates/computed

// Override specific parameters
l('Article title', 'content') // Not reactive
lr('French text', 'ui', 'fr') // Reactive

Features

• Reactive translations with automatic UI updates
• SSR support for Nuxt.js applications
• Smart caching with context-aware storage
• Language detection with browser locale support
• Limit monitoring with usage tracking
• TypeScript support with full type definitions
• Multiple frameworks - Vue.js, Nuxt.js, vanilla JavaScript

Backend Requirements

Your translation service needs these endpoints:

• POST /translate - Translate texts
• GET /languages - Available languages
• GET /limit - API usage limits
• GET /health - Service health check

See Backend Integration for detailed API specifications and setup guide.

License

Apache 2.0