@ghoststrings/ai

v1.0.1

Published

2 months ago

Premium Over-the-Air (OTA) translation and content management SDK for Web, React, and Vanilla JavaScript applications.

0High
0Medium
0Low

ahmadshahwaiz

ghoststrings localization translation i18n ota over-the-air react nextjs typescript

GhostStrings Web SDK 👻🚀

The Premium Over-the-Air (OTA) Content & Localization Layer for Web Apps.

Update your website's copy, translations, marketing tags, and placeholder text instantly across any browser, framework (React, Vue, Next.js, etc.), or raw HTML pages — without a single developer build, redeploy, or page reload.

✨ Features

Zero Layout Shift (CLS): Instant UI rendering from local storage cache, synchronized seamlessly in the background.
Modern Bundling: Dual CommonJS & ES Module outputs with built-in TypeScript definitions out-of-the-box.
React Native bindings: Includes hooks, context providers, and reactive text elements natively.
Auto DOM Interception: Scan, intercept, and live-update standard HTML nodes automatically using the intuitive data-lv attribute.
Dynamic Placeholders: Empower product and marketing teams to use simple template variables like {name} that are interpolated in real-time.

📦 Installation

Install the lightweight, zero-dependency SDK in your web project:

npm install @ghoststrings/ai

🛠️ Integration Quick Start

1. Vanilla JavaScript / TypeScript

For client-side vanilla projects or modern module bundles (Vite, Webpack, etc.):

import { GhostStrings } from '@ghoststrings/ai';

// Initialize the core SDK
const gs = new GhostStrings({
  projectId: 'pk_your_production_key', // Use dk_ for testing/development
  lang: 'es', // Optional default language code
  cacheTtl: 3600, // Background updates checked hourly
  enableDomInterception: true // Enable auto data-lv scanner
});

// Load strings from local storage instantly and request backend updates in the bg
await gs.init();

// Translate keys dynamically
const title = gs.get('hero_title', 'Welcome to our platform!');

// Support for template variables
const welcome = gs.get('welcome_msg', 'Hello {name}!', { name: 'Alice' });

⚛️ 2. React / Next.js / Remix

GhostStrings provides first-class React bindings. Wrap your application tree inside the GhostStringsProvider and leverage reactive hooks:

A. Set up the Provider

import React from 'react';
import { GhostStringsProvider } from '@ghoststrings/ai';

const config = {
  projectId: 'pk_your_production_key',
  fallbacks: {
    hero_title: 'Welcome to our premium app!',
    welcome_msg: 'Hello {username}!'
  }
};

export default function App() {
  return (
    <GhostStringsProvider config={config}>
      <MainLayout />
    </GhostStringsProvider>
  );
}

B. Consume Strings with Hooks & Components

import React from 'react';
import { useGhostStrings, GhostText } from '@ghoststrings/ai';

export function MainLayout() {
  const { getString, loading, setLanguage } = useGhostStrings();

  return (
    <div>
      {/* 1. Standard hook usage */}
      <h1>{getString('hero_title')}</h1>

      {/* 2. Standard hook with dynamic variables */}
      <p>{getString('welcome_msg', 'Welcome!', { username: 'Ahmad' })}</p>

      {/* 3. Sleek reactive Component (optimal for performance) */}
      <GhostText 
        id="cta_btn" 
        fallback="Join Now" 
        className="btn-primary" 
      />

      {/* 4. Live language switching */}
      <button onClick={() => setLanguage('fr')}>Switch to French</button>
    </div>
  );
}

🌐 3. Script Tag Integration (Low-Code / Webflow / HTML)

If you are using a static site generator, Webflow, Shopify, or raw HTML pages, drop in the compiled global browser bundle:

<head>
  <!-- Load the GhostStrings Premium Global Script -->
  <script 
    src="https://api.ghoststrings.ai/sdk.js" 
    data-project="pk_your_production_key"
    data-track="prod"
  ></script>
</head>
<body>
  <!-- Tag elements with data-lv attribute to intercept automatically -->
  <h1 data-lv="hero_title">Original Static Title</h1>
  <p data-lv="welcome_msg" data-lv-vars='{"name": "Alice"}'>Hello!</p>

  <script>
    // Listen for the ready event to perform custom scripting
    document.addEventListener('ghoststrings-ready', (e) => {
      const strings = e.detail;
      console.log('GhostStrings fully synchronized!', strings);
    });
  </script>
</body>

🔐 Security & Core Design

GhostStrings respects user privacy. We do not track or send Personally Identifiable Information (PII) to our servers. Only public localization string keys and localized copy are transferred securely.

📄 License

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

Built with ❤️ by GhostStrings