Integrar scripts de terceiros numa Aplicação de Página Única (SPA) como React requer uma manipulação cuidadosa do DOM. Não pode simplesmente colar uma tag 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 da thread principal, injeção otimizada de tags SEO e limpeza adequada ao desmontar.

Pré-requisitos

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

Chave da API do Projeto: Seu identificador único (Encontrado em Configurações).

Línguas-Alvo: A lista de códigos ISO ativados para o seu projeto (ex: 'hi', 'es', 'fr').

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

Etapa 1: Criar o Componente Injetor

Construindo a ponte.

Criaremos um componente especializado cujo único trabalho é gerir a injeção de tags SEO e o script de tradução na 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 Detalhada do Código: Porquê isto funciona

useEffect Hook: Isto garante que o código só é executado após a montagem do componente, prevenindo 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 hindi do seu site.

Desempenho (Preconnect): O dns-prefetch e ainda pré-conexão as 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 o widget de tradução aparecer.

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

Passo 2: Inicializar na Aplicação Raiz

Ativando a camada.

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

Ação: Importe e monte 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 permaneça ativo independentemente da rota (página) para a qual o usuário navega.

Não Visual: Uma vez que 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.

Depois de salvar e executar sua aplicação React (npm start quer yarn dev), execute estas verificações:

A Verificação Visual: Vê o widget de Comutador de Idioma a flutuar na posição definida por posX e ainda posY?

A Verificação do DOM: Abra o Chrome DevTools (F12) → Separador Elements → Expanda .

Verifique se vê as marcas.

Verificar o page_translations.js o script está presente na parte inferior 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 usuário antes de traduzir.

Como Integrar o MultiLipi no seu site React