Integrar scripts de terceiros numa Aplicação de Página Única (SPA) como o React requer um manuseamento cuidadoso do DOM. Não pode simplesmente colar uma etiqueta de script num ficheiro HTML se quiser controlo dinâmico. Este guia demonstra como criar um dedicado "Componente Injetor"— uma forma modular, limpa e amigável para React de carregar o motor MultiLipi.

Este método garante que não há bloqueio do thread principal, injeção otimizada de etiquetas SEO e limpeza adequada após a desmontagem.

Pré-requisitos

Antes de prosseguir, certifique-se de que tem o seguinte do seu Painel MultiLipi:

Chave API do Projeto: O seu identificador único (Encontrado em Definições).

Idiomas Alvo: A lista de códigos ISO ativados para o seu projeto (por exemplo, 'hi', 'es', 'fr').

Domínio: O seu domínio de produção (por exemplo, yoursite.com).

Passo 1: Criar o Componente Injetor

A construir a ponte.

Criaremos um componente especializado cujo único trabalho é gerir a injeção de tags SEO e o script de tradução no do seu documento.

Ação: Crie um ficheiro chamado multilipi.tsx (ou .js) no seu src/ pasta e cole o código abaixo.

TypeScript

// multilipi.tsx
import { useEffect } from "react";

const LANGUAGES = ["hi", "ar"] as const; // Replace with your languages
const DOMAIN = "example.com";           // Replace with your actual domain
const MULTILIPI_KEY = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"; // Replace with your actual key

export default function AddScriptToHead() {
  useEffect(() => {
    const head = document.head;
    const added: HTMLElement[] = [];

    const add = <T extends HTMLElement>(el: T) => {
      head.appendChild(el);
      added.push(el);
      return el;
    };

    // Alternate hreflang links
    LANGUAGES.forEach((lang) => {
      const link = document.createElement("link");
      link.rel = "alternate";
      link.hreflang = lang;
      link.href = `https://${lang}.${DOMAIN}/`;
      add(link);
    });

    // DNS prefetch & preconnect
    const dns = document.createElement("link");
    dns.rel = "dns-prefetch";
    dns.href = "//multilipiseo.multilipi.com";
    add(dns);

    const preconnect = document.createElement("link");
    preconnect.rel = "preconnect";
    preconnect.href = "https://multilipiseo.multilipi.com";
    preconnect.crossOrigin = "anonymous";
    add(preconnect);

    // Add MultiLipi translation script
    const script = document.createElement("script");
    script.src = "https://script-cdn.multilipi.com/static/JS/page_translations.js";
    script.crossOrigin = "anonymous";
    script.dataset.posX = "50";
    script.dataset.posY = "50";
    script.setAttribute("multilipi-key", MULTILIPI_KEY);
    script.setAttribute("mode", "auto");
    add(script);

    // Cleanup on component unmount
    return () => {
      added.forEach((el) => el.parentNode?.removeChild(el));
    };
  }, []);

  return null;
}

Análise Profunda do Código: Por que isto funciona

useEffect Hook: Isto garante que o código é executado apenas após a montagem do componente, evitando bloqueios durante a fase inicial de hidratação.

Automação de SEO (Hreflang): O código itera através do seu array LANGUAGES e injeta dinamicamente tags. Isto é crucial para dizer ao Google que hi.example.com é a versão em hindi do seu site.

Desempenho (Preconnect): O dns-prefetch e preconnect linhas dizem ao navegador para resolver o endereço IP do servidor MultiLipi antes mesmo de o script ser solicitado. Isto reduz significativamente o tempo necessário para que o widget de tradução apareça.

Função de Limpeza (return () => ...): No React, os componentes podem ser re-renderizados. Esta lógica rastreia todos os elementos que adicionámos (added.push(el)) e remove-os se o componente for desmontado. Isto evita tags de script duplicadas e fugas de memória.

Passo 2: Inicializar na Aplicação Raiz

Ativar a camada.

Agora que a lógica está encapsulada, precisamos de a colocar no nível mais alto da árvore da sua aplicação, tipicamente App.tsx or App.js.

Ação: Importar e montar o componente.

TypeScript

// App.tsx
import AddScriptToHead from './multilipi'; // adjust the path as needed

function App() {
  return (
    <>
      {/* Load the MultiLipi script */}
      <AddScriptToHead />

      {/* Rest of your App UI */}
    </>
  );
}

export default App;

Porquê colocá-lo aqui?

Escopo Global: Colocar em App.tsx garante que o motor de tradução permanece ativo independentemente da rota (página) para a qual o utilizador navega.

Não Visual: Como o componente retorna null, não afeta o layout ou o espaçamento da sua UI. Funciona silenciosamente em segundo plano.

Lista de Verificação de Verificação

Como confirmar a integração bem-sucedida.

Assim que guardar e executar a sua aplicação React (npm start or yarn dev), execute estas verificações:

A Verificação Visual: Vê o widget do Seletor de Idiomas a flutuar na posição definida por posX e posY?

A Verificação do DOM: Abra as Ferramentas de Desenvolvedor do Chrome (F12) → Separador Elementos → Expanda .

Verifique se vê a etiquetas.

Verifique a page_translations.js script está presente no final do head.

A Verificação de Rede: Abra o separador Rede e filtre por "JS". Certifique-se de que page_translations.js está a carregar com o estado 200 OK.

Opções de Configuração Adicionais

No código fornecido, verá script.dataset propriedades. Pode ajustar estes valores para personalizar o comportamento:

script.dataset.posX / posY: Ajuste estes números (0-100) para mover a posição padrão do widget flutuante no ecrã.

script.setAttribute("mode", "auto"):

"auto": Tenta traduzir automaticamente com base no idioma do navegador.

"manual": Aguarda a interação do utilizador antes de traduzir.

Como Integrar o MultiLipi no Seu Website React