neeto-customize-text-nano

The neeto-customize-text-nano allows organizations to customize UI text by overriding default i18next text keys. The nano exports the @bigbinary/neeto-customize-text-frontend NPM package and neeto-customize-text-engine Rails engine for development.

Contents

1. Development with Host Application
   • Engine
     • Installation
     • Configuration
     • Usage
   • Frontend package
     • Installation
     • Instructions for development
     • Components
     • Utilities
     • Hooks
2. Instructions for Publishing

Development with Host Application

Engine

The engine provides the backend for storing and retrieving custom text overrides per organization.

Installation

1. Add this line to your application's Gemfile:

   source "NEETO_GEM_SERVER_URL" do
     # ...existing gems
   
     gem "neeto-customize-text-engine"
   
     # Use this for development:
     # gem "neeto-customize-text-engine", path: "../neeto-customize-text-nano"
   end

2. And then execute:

   bundle install

3. Add this line to your application's config/routes.rb file:

   mount NeetoCustomizeTextEngine::Engine, at: "/neeto_customize_text"

   NOTE: The mount point must be /neeto_customize_text and cannot be changed to any other path.

4. Run the following command to copy the migration from the engine to the host application's db/migrate directory:

   bundle exec rails neeto_customize_text_engine:install:migrations

   This copies the engine's migration file into your app with a timestamp prefix and an neeto_customize_text_engine suffix so Rails knows its origin. The copied file will look like db/migrate/<timestamp>_create_neeto_customize_text.neeto_customize_text_engine.rb.

5. Run the migration to create the neeto_customize_text_custom_texts table:

   bundle exec rails db:migrate

Configuration

Create an initializer at config/initializers/neeto_customize_text_engine.rb:

NeetoCustomizeTextEngine.configure do |config|
  config.en_text_file_path = Rails.root.join("app/javascript/src/translations/en.json")
  config.max_overrides_per_org = 500
  config.max_value_length = 2000
end

| Option | Default | Description | | --- | --- | --- | | en_text_file_path | — | Required. Path to the host app's English text JSON file (en.json). Used to validate that overridden keys exist and interpolation tokens match. | | max_overrides_per_org | 500 | Maximum number of custom text entries allowed per organization. | | max_value_length | 2000 | Maximum character length for a custom text value. |

Usage

The engine exposes the following API endpoints (all scoped under the mount path):

• GET /custom_texts?locale=en — Returns all custom text overrides for the current organization as a flat key-value hash.
• PUT /custom_texts/bulk_update — Accepts a JSON body with a custom_texts object. Keys map to text keys; values are the custom text (or null to delete).
• DELETE /custom_texts/:id — Deletes a single custom text override.

The engine also provides a helper method for passing custom texts to the frontend:

# In your application layout or controller
include NeetoCustomizeTextEngine::ApplicationHelper

# Returns { customize_text: { "key" => "custom value", ... } }
customize_text_client_props

Frontend package

The package exports a CustomizeTextDashboard component that provides a settings UI for admins to search, override, and reset text keys. It also exports utility functions for applying custom texts at runtime.

Installation

Install the package:

yarn add @bigbinary/neeto-customize-text-frontend

Instructions for development

Check the Frontend package development guide for step-by-step instructions to develop the frontend package.

Components

CustomizeTextDashboard

This component provides a dashboard for organization admins to customize UI text. It supports searching, editing with auto-save, language selection, interpolation token validation, and resetting overrides to defaults.

Props

• config: Configuration object with the following keys:

| Key | Type | Required | Description | | --- | --- | --- | --- | | apiUrl | string | Yes | The base URL for the custom texts API (e.g., /neeto_customize_text/custom_texts). | | defaultTexts | object | Yes | The default English text object (nested JSON from en.json). | | textImports | object | No | A map of locale codes to dynamic import functions for loading locale-specific default texts. | | breadcrumbs | array | No | Breadcrumb items passed to the Header component. | | helpPopoverProps | object | No | Props for the help popover on the page title. | | excludedKeyPrefixes | array | No | Array of key prefixes to exclude from the dashboard (e.g., ["admin.", "internal."]). | | title | string | No | Page title. Defaults to "Customize text". |

Usage

import { CustomizeTextDashboard } from "@bigbinary/neeto-customize-text-frontend";

import enTexts from "translations/en.json";

const CustomizeText = () => (
  <CustomizeTextDashboard
    config={{
      apiUrl: "/neeto_customize_text/custom_texts",
      defaultTexts: enTexts,
      breadcrumbs: [{ text: "Settings", link: "/settings" }],
      excludedKeyPrefixes: ["admin."],
      textImports: {
        fr: () => import("translations/fr.json"),
        es: () => import("translations/es.json"),
      },
    }}
  />
);

Utilities

applyCustomizeText(customTexts)

Applies custom text overrides to the i18next resource bundle at runtime. Call this during app initialization with the data from customize_text_client_props.

import { applyCustomizeText } from "@bigbinary/neeto-customize-text-frontend";

// During app initialization
const { customize_text } = window.globalProps;
applyCustomizeText(customize_text);

flattenKeys(obj) / unflattenKeys(flatObj)

Helper functions to convert between nested and flat key-value representations.

import { flattenKeys, unflattenKeys } from "@bigbinary/neeto-customize-text-frontend";

flattenKeys({ a: { b: "hello" } }); // => { "a.b": "hello" }
unflattenKeys({ "a.b": "hello" }); // => { a: { b: "hello" } }

Hooks

refetchCustomizeText(queryClient)

Invalidates the custom text query cache, triggering a refetch.

import { useQueryClient } from "@tanstack/react-query";
import { refetchCustomizeText } from "@bigbinary/neeto-customize-text-frontend";

const queryClient = useQueryClient();
refetchCustomizeText(queryClient);

Instructions for Publishing

Consult the building and releasing packages guide for details on how to publish.