Deploying Localess

Introduction

Localess is a powerful open-source translation management tool and headless content management system built with Angular and Firebase. Designed to simplify the process of managing multilingual content, Localess enables teams to easily translate website and application content into multiple languages while leveraging artificial intelligence to accelerate the translation process.

With its user-friendly interface and Firebase integration, Localess ensures that translations are stored securely and can be accessed from anywhere. The real-time localization editing capabilities mean changes appear instantly without requiring application rebuilds, making it ideal for dynamic content management.

Key highlights of Localess:

• Translation Management: Organize and manage translations across multiple languages
• AI-Powered Translation: Integrate with Google Translate for automated translations
• Headless CMS: Manage content independently of your frontend framework
• Real-Time Updates: Edit content without rebuilding your application
• Firebase Backend: Secure, scalable storage with Firebase integration
• User-Friendly Interface: Clean, intuitive interface for content management
• Team Collaboration: Multiple users can work on translations simultaneously
• API Access: RESTful API for programmatic content access
• Version Control: Track changes and revert when needed
• Free Forever: Open-source with no usage limits
• Active Development: Regular updates and community support

This guide walks through deploying Localess on Klutch.sh, configuring Firebase integration, and setting up your translation management workflow.

Why Deploy Localess on Klutch.sh

Deploying Localess on Klutch.sh provides several advantages:

Managed Hosting: Focus on content management while Klutch.sh handles infrastructure.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure API access.

GitHub Integration: Connect your configuration repository directly from GitHub for automatic deployments.

Custom Domains: Use your own domain for your Localess dashboard and API endpoints.

Scalable Resources: Allocate CPU and memory based on your content volume and team size.

Environment Variable Security: Store Firebase credentials securely through Klutch.sh’s environment variable system.

Always Available: Your CMS remains accessible 24/7 for content updates and API requests.

Prerequisites

Before deploying Localess on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• A Firebase account and project
• Basic familiarity with Docker and Firebase
• (Optional) A custom domain for your Localess instance
• (Optional) Google Cloud Translation API key for AI translations

Understanding Localess Architecture

Localess uses a modern architecture built on Angular and Firebase:

Angular Frontend: The administrative interface is built with Angular, providing a responsive, modern user experience for content management.

Firebase Backend: All data is stored in Firebase Firestore, providing real-time synchronization and secure access. Firebase Authentication handles user management.

API Layer: A RESTful API enables your applications to fetch content, with real-time updates via Firebase SDK.

AI Translation: Optional integration with Google Translate API for automated translation suggestions.

Setting Up Firebase

Before deploying Localess, configure your Firebase project:

Create Firebase Project

1. Go to the Firebase Console
2. Click Add project
3. Name your project and configure settings
4. Enable Google Analytics if desired

Enable Firestore

1. Navigate to Firestore Database
2. Click Create database
3. Choose production mode
4. Select a location near your users

Enable Authentication

1. Navigate to Authentication
2. Click Get started
3. Enable Email/Password provider
4. Optionally enable additional providers (Google, GitHub, etc.)

Get Configuration

1. Navigate to Project settings (gear icon)
2. Under Your apps, click the web icon (</>)
3. Register your app
4. Copy the Firebase configuration object

Preparing Your Repository

To deploy Localess on Klutch.sh, create a GitHub repository containing your Docker configuration.

Repository Structure

localess-deploy/
├── Dockerfile
├── docker-compose.yml
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM node:20-alpine AS builder

# Clone and build Localess
RUN apk add --no-cache git
RUN git clone https://github.com/Lessify/localess.git /app
WORKDIR /app

# Install dependencies
RUN npm ci

# Build the application
RUN npm run build

# Production stage
FROM nginx:alpine

# Copy built files
COPY --from=builder /app/dist/localess/browser /usr/share/nginx/html

# Copy nginx configuration
COPY nginx.conf /etc/nginx/conf.d/default.conf

EXPOSE 80

CMD ["nginx", "-g", "daemon off;"]

Creating Nginx Configuration

Create an nginx.conf file:

server {
    listen 80;
    server_name localhost;
    root /usr/share/nginx/html;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /api {
        proxy_pass https://firestore.googleapis.com;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml;
}

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local
node_modules

Environment Variables Reference

Localess uses Firebase configuration through environment variables:

Variable	Required	Description
FIREBASE_API_KEY	Yes	Firebase API key
FIREBASE_AUTH_DOMAIN	Yes	Firebase auth domain
FIREBASE_PROJECT_ID	Yes	Firebase project ID
FIREBASE_STORAGE_BUCKET	Yes	Firebase storage bucket
FIREBASE_MESSAGING_SENDER_ID	Yes	Firebase messaging sender ID
FIREBASE_APP_ID	Yes	Firebase app ID
GOOGLE_TRANSLATE_API_KEY	No	API key for AI translations

Deploying Localess on Klutch.sh

Once your repository is prepared, follow these steps to deploy:

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile nginx.conf .dockerignore
git commit -m "Initial Localess deployment configuration"
git remote add origin https://github.com/yourusername/localess-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “localess” or “translations”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Localess configuration.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 80

Set Environment Variables

In the environment variables section, add your Firebase configuration:

Variable	Value
FIREBASE_API_KEY	Your Firebase API key
FIREBASE_AUTH_DOMAIN	your-project.firebaseapp.com
FIREBASE_PROJECT_ID	your-project-id
FIREBASE_STORAGE_BUCKET	your-project.appspot.com
FIREBASE_MESSAGING_SENDER_ID	Your sender ID
FIREBASE_APP_ID	Your app ID

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Start the Localess container
• Provision an HTTPS certificate

Access Localess

Once deployment completes, access your Localess instance at https://your-app-name.klutch.sh.

Initial Setup

First-Time Configuration

When you first access Localess:

1. Sign Up: Create an admin account using Firebase Authentication
2. Create Organization: Set up your organization or project
3. Add Languages: Configure the languages you need to support
4. Invite Team: Add team members with appropriate roles

Configuring Languages

Set up your supported languages:

1. Navigate to Settings → Languages
2. Add your source language (e.g., English)
3. Add target languages for translation
4. Set language codes (en, es, fr, de, etc.)

Creating Translation Keys

Organize your translations:

1. Navigate to Translations
2. Create namespaces for organization (common, errors, features, etc.)
3. Add translation keys
4. Enter source language content

Managing Translations

Adding Translations

Add translations manually:

1. Select a translation key
2. Click on the target language
3. Enter the translated content
4. Save changes

AI-Powered Translation

Use Google Translate for suggestions:

1. Configure Google Translate API key in settings
2. Select keys to translate
3. Click Auto-translate
4. Review and edit suggestions
5. Approve translations

Bulk Operations

Manage translations efficiently:

• Import: Upload translation files (JSON, CSV)
• Export: Download translations for backup or use
• Batch Edit: Edit multiple keys at once
• Search: Find specific keys or content

Integrating with Your Application

JavaScript/TypeScript

Fetch translations via Firebase:

import { initializeApp } from 'firebase/app';
import { getFirestore, collection, getDocs } from 'firebase/firestore';

const app = initializeApp(firebaseConfig);
const db = getFirestore(app);

async function getTranslations(locale) {
  const translationsRef = collection(db, 'translations', locale);
  const snapshot = await getDocs(translationsRef);

  const translations = {};
  snapshot.forEach(doc => {
    translations[doc.id] = doc.data();
  });

  return translations;
}

REST API

Use the Localess API directly:

# Get translations for a language
curl https://your-localess.klutch.sh/api/translations/en

# Get specific namespace
curl https://your-localess.klutch.sh/api/translations/en/common

React Integration

import { useState, useEffect } from 'react';

function useTranslations(locale) {
  const [translations, setTranslations] = useState({});

  useEffect(() => {
    // Fetch from Localess API
    fetch(`https://your-localess.klutch.sh/api/translations/${locale}`)
      .then(res => res.json())
      .then(data => setTranslations(data));
  }, [locale]);

  return (key) => translations[key] || key;
}

function MyComponent() {
  const t = useTranslations('en');

  return <h1>{t('welcome.title')}</h1>;
}

Content Management

Creating Content Types

Define your content structures:

1. Navigate to Content Types
2. Create new type (e.g., “Blog Post”, “Product”)
3. Define fields (title, body, image, etc.)
4. Configure localization settings

Managing Content

Create and edit content:

1. Navigate to Content
2. Select content type
3. Create new entries
4. Edit in multiple languages
5. Publish when ready

Scheduling

Plan content releases:

1. Set publish dates
2. Configure automatic publishing
3. Schedule translations completion

Team Collaboration

User Roles

Configure access levels:

• Admin: Full access to all features
• Editor: Create and edit content
• Translator: Manage translations only
• Viewer: Read-only access

Workflow

Set up translation workflows:

1. Draft: Initial content creation
2. Review: Content needs verification
3. Approved: Ready for translation
4. Translated: Translation complete
5. Published: Live content

Production Best Practices

Security Recommendations

• Firebase Rules: Configure Firestore security rules
• API Keys: Restrict API key usage
• Authentication: Use strong authentication methods
• Role-Based Access: Implement appropriate permissions

Performance Optimization

• Caching: Implement client-side caching
• CDN: Use Firebase CDN for content delivery
• Batch Requests: Group API calls
• Lazy Loading: Load translations on demand

Backup Strategy

Protect your translations:

1. Regular Exports: Download translations periodically
2. Firebase Backups: Configure Firestore backups
3. Version Control: Track changes in Git

Troubleshooting Common Issues

Authentication Errors

Symptoms: Cannot log in or access dashboard.

Solutions:

• Verify Firebase configuration
• Check authentication providers are enabled
• Review Firebase Console for errors

Translation Not Updating

Symptoms: Changes don’t appear in application.

Solutions:

• Check API endpoint configuration
• Verify cache settings
• Review Firestore rules
• Test direct API calls

AI Translation Not Working

Symptoms: Auto-translate feature fails.

Solutions:

• Verify Google Translate API key
• Check API quota and limits
• Review console for errors

Additional Resources

• Localess GitHub Repository
• Firebase Documentation
• Google Cloud Translation Documentation
• Klutch.sh Deployments

Conclusion

Deploying Localess on Klutch.sh gives you a powerful translation management system with Firebase backend integration. The combination of real-time editing, AI-powered translation, and headless CMS capabilities makes it ideal for managing multilingual content.

With team collaboration features, workflow management, and flexible API access, Localess scales from small projects to enterprise applications. The Firebase integration ensures secure, scalable storage with real-time synchronization across your applications.

Whether you’re localizing a website, managing app content, or building a multilingual product, Localess on Klutch.sh provides the tools needed for efficient translation management.