Release/0.3.0 (#7)

* Optimised SSR flow
* Nested Formatting for SSR

Author: wadeyw

README.md

@@ -26,7 +26,7 @@ npm install react-autolocalise
 yarn add react-autolocalise
 ```
 
-## Usage
+## React Client Side Component Usage
 
 ### Initialize the SDK
 
@@ -117,7 +117,7 @@ const MyComponent = () => {
 
 This SDK provides comprehensive SSR support through middleware-based locale detection and server components. Here's how to implement end-to-end server-side translation:
 
-### Middleware Setup
+### Middleware Setup for language detection
 
 Create a middleware file to detect user's locale from request headers or URL parameters:
 
@@ -146,45 +146,96 @@ export const config = {
 };
 ```
 
+### Initialize Translation Service (Singleton Pattern)
+
+The SDK uses a singleton pattern for the TranslationService to ensure efficient caching and batch processing. Create a utility file to manage the translator instance:
+
+```typescript
+// utils/translator.ts
+import ServerTranslation from "react-autolocalise/server";
+
+const config = {
+  apiKey: "your-api-key",
+  sourceLocale: "fr",
+  targetLocale: "en",
+};
+
+// Simple function to get a translator instance
+export function getTranslator() {
+  return new ServerTranslation(config);
+}
+```
+
 ### Server Component Implementation
 
 Create server components that utilize the detected locale:
 
 > **Note**: For server-side rendering, all translations must be completed before sending the response to the client. This requires a two-step process: first mark texts for translation using t() , then execute all translations in a single batch with execute() . This ensures all translations are ready before rendering occurs.
 
-```tsx
-import { ServerTranslation } from "react-autolocalise/server";
-import { headers } from "next/headers";
-
-export default async function ServerComponent() {
-  const headersList = headers();
-  const targetLocale = headersList.get("x-locale") || "en";
+**Basic Usage:**
 
-  const config = {
-    apiKey: "your-api-key",
-    sourceLocale: "en",
-    targetLocale,
-  };
+```tsx
+import { getTranslator } from "@/utils/translator";
 
-  // Create a server-side translation instance
-  const translator = new ServerTranslation(config);
+async function ServerComponent() {
+  const translator = getTranslator();
 
   // Mark texts for translation
   const title = translator.t("Hello from Server Component");
   const description = translator.t(
     "This component is rendered on the server side"
   );
 
-  // Execute all translations at once
+  // Execute all translations in a single batch
   await translator.execute();
 
+  // Get translated texts
   return (
     <div>
       <h1>{translator.get(title)}</h1>
       <p>{translator.get(description)}</p>
     </div>
   );
 }
+
+export default ServerComponent;
+```
+
+**Use with nested text formatting:**
+
+For components with styled text, use `tFormatted()` and `getFormatted()` to preserve formatting:
+
+```tsx
+import { getTranslator } from "@/utils/translator";
+
+async function FormattedServerComponent() {
+  const translator = getTranslator();
+
+  // Mark formatted text with nested styling for translation
+  const formattedContent = (
+    <>
+      Hello, we <span style={{ color: "red" }}>want</span> you to be{" "}
+      <strong style={{ fontWeight: "bold" }}>happy</strong>!
+    </>
+  );
+  // Mark the formatted texts for translation
+  translator.tFormatted(formattedContent);
+
+  // Also mark some regular text
+  const subtitle = translator.t("Server-side nested formatting example");
+
+  // Execute all translations in a single batch
+  await translator.execute();
+
+  return (
+    <div>
+      <h3>{translator.get(subtitle)}</h3>
+      <p>{translator.getFormatted(formattedContent)}</p>
+    </div>
+  );
+}
+
+export default FormattedServerComponent;
 ```
 
 ### SEO Considerations

package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "react-autolocalise",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Auto-translation SDK for React and Next.js applications with SSR support",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",

src/components/FormattedText.tsx

@@ -1,5 +1,9 @@
 import React from "react";
 import { useAutoTranslate } from "../context/TranslationContext";
+import {
+  extractTextAndStyles,
+  restoreStyledText,
+} from "../utils/textFormatting";
 
 /**
  * FormattedText is a component that handles nested text formatting during translation.
@@ -30,70 +34,6 @@ export const FormattedText: React.FC<FormattedTextProps> = ({
 }) => {
   const { t } = useAutoTranslate();
 
-  /**
-   * Extracts text content and styled nodes from the children prop.
-   * Converts nested span elements into a template format (e.g., <0>styled text</0>)
-   * while preserving the original styled nodes for later restoration.
-   *
-   * @param nodes - The React nodes to process (typically the children prop)
-   * @returns An object containing the template text and an array of styled nodes
-   */
-  const extractTextAndStyles = (
-    nodes: React.ReactNode
-  ): {
-    text: string;
-    styles: Array<{ node: React.ReactElement; text: string }>;
-  } => {
-    const styles: Array<{ node: React.ReactElement; text: string }> = [];
-    let text = "";
-
-    const processNode = (node: React.ReactNode) => {
-      if (typeof node === "string") {
-        text += node;
-        return;
-      }
-
-      if (React.isValidElement(node)) {
-        const children = node.props.children;
-        if (typeof children === "string") {
-          text += `<${styles.length}>${children}</${styles.length}>`;
-          styles.push({ node, text: children });
-        } else if (Array.isArray(children)) {
-          children.forEach(processNode);
-        } else if (children) {
-          processNode(children);
-        }
-      }
-    };
-
-    processNode(nodes);
-    return { text, styles };
-  };
-
-  /**
-   * Restores the styled nodes in the translated text by replacing template markers
-   * with the original styled components, but with translated content.
-   *
-   * @param translatedText - The translated text containing template markers
-   * @param styles - Array of original styled nodes and their text content
-   * @returns An array of React nodes with restored styling and translated content
-   */
-  const restoreStyledText = (
-    translatedText: string,
-    styles: Array<{ node: React.ReactElement; text: string }>
-  ): React.ReactNode[] => {
-    const parts = translatedText.split(/(<\d+>.*?<\/\d+>)/g);
-    return parts.map((part, index) => {
-      const match = part.match(/<(\d+)>(.*?)<\/\1>/);
-      if (match) {
-        const [, styleIndex, content] = match;
-        const { node } = styles[parseInt(styleIndex)];
-        return React.cloneElement(node, { key: `styled-${index}` }, content);
-      }
-      return part;
-    });
-  };
-
   const { text, styles } = extractTextAndStyles(children);
   const translatedText = t(text, persist);
 

src/index.ts

@@ -19,5 +19,9 @@ const autoTranslate = {
 };
 
 export { FormattedText } from "./components/FormattedText";
+export {
+  extractTextAndStyles,
+  restoreStyledText,
+} from "./utils/textFormatting";
 
 export default autoTranslate;