Traducir tu web PHP es esencial para llegar a una audiencia global. Azbox proporciona una potente librería PHP que simplifica el proceso de localización gestionando las traducciones en la nube y traduciendo automáticamente el contenido de tu web. Esta guía te guiará a través del proceso completo de traducir una web PHP usando Azbox, desde la configuración del proyecto hasta la implementación.

Entendiendo la Integración de Azbox PHP

Azbox es una plataforma de gestión de traducciones basada en la nube que te permite:

Gestionar traducciones centralmente en la plataforma en la nube de Azbox
Traducir automáticamente el contenido de tu web
Soportar múltiples idiomas sin cambios en el código
Actualizar traducciones en tiempo real
Importar keywords existentes de tu web
Colaborar con traductores a través de la plataforma Azbox

Requisitos Previos

Antes de comenzar, asegúrate de tener:

PHP 7.0 o superior instalado
Composer (opcional, pero recomendado)
Cuenta Azbox: Plan de Azbox de pago (Starter o superior)
Proyecto Azbox: Proyecto Azbox configurado con tus traducciones
API Key y Project ID de tu proyecto Azbox

Paso 1: Crear un Proyecto Web en Azbox

El primer paso es crear un nuevo proyecto en tu panel de Azbox. Tu proyecto será tu base operativa para gestionar las traducciones de tu web.

Inicia sesión en tu panel de Azbox
Haz clic en el botón Create Project en la esquina superior derecha del panel
Aparecerá un popup donde puedes configurar tu proyecto:
- Project Name: Introduce un nombre descriptivo para tu proyecto
- Project Type: Selecciona Web como tipo de proyecto
- Languages: Selecciona tu idioma original y los idiomas de destino a los que quieres traducir
- Members: Opcionalmente añade miembros del equipo para colaborar en las traducciones
Haz clic en Create para finalizar la configuración de tu proyecto

Tu proyecto aparecerá ahora en tu panel, y podrás ver tu Project ID que necesitarás para la integración.

Paso 2: Importar Keywords de Tu Web

Si ya tienes una web con Azbox instalado, puedes importar todas las keywords existentes automáticamente. Esto te ahorra tiempo al no tener que añadir keywords manualmente.

En el panel de tu proyecto, haz clic en el botón Import from website (el botón con el icono de globo)

Panel de Azbox con Botón de Importar

Aparecerá un diálogo modal titulado “Import from website”

Modal de Importar desde Web

Introduce la URL de tu web que tiene el plugin de Azbox instalado (por ejemplo, https://example.com)
Haz clic en Import para iniciar el proceso de importación

Azbox escaneará automáticamente tu web e importará todas las keywords que se están utilizando. Esto incluye:

Todo el contenido de texto que necesita traducción
Keywords de tu instalación existente de Azbox
Estructura y organización del contenido

Después de que la importación se complete, verás todas tus keywords en el panel del proyecto, listas para ser traducidas o gestionadas.

Gestión Manual de Keywords

Si prefieres añadir keywords manualmente o necesitas añadir nuevas:

Haz clic en el botón Add Keyword en la esquina superior derecha
Introduce el texto de la keyword
Opcionalmente asígnala a una categoría
La keyword será traducida automáticamente a todos tus idiomas configurados

Paso 3: Instalar la Librería Azbox PHP

Hay dos formas de instalar la librería Azbox PHP: usando Composer (recomendado) o instalación manual.

Instalar con Composer (Recomendado)

Si estás usando Composer, instala el paquete vía Composer:

composer require azbox/azbox-php

Esto descargará automáticamente la librería y sus dependencias.

Instalación Manual

Si no usas Composer, puedes descargar la librería manualmente:

Descarga el archivo azbox.php y el directorio lib del repositorio de Azbox PHP
Cópialos a tu directorio del proyecto
Incluye el archivo en tu código PHP:

require_once 'ruta/a/azbox.php';

Paso 4: Obtener Tus Credenciales de Azbox

Antes de configurar la librería, necesitarás obtener tus credenciales de tu proyecto Azbox:

API Key: Se encuentra en la configuración de tu proyecto Azbox
Project ID: El identificador de tu proyecto Azbox (visible en el panel de tu proyecto)

Puedes encontrar estos datos en tu panel de Azbox en la configuración de tu proyecto o en la vista general del proyecto.

Paso 5: Configurar Azbox en Tu Aplicación PHP

Para inicializar Azbox, necesitas añadir el código de inicialización al principio de la ejecución de PHP. Esto normalmente se hace en index.php o tu punto de entrada principal de la aplicación.

Configuración Básica

Aquí está el código de configuración básica:

<?php
// Si usas Composer
require __DIR__ . '/vendor/autoload.php';

// Si usas instalación manual
// require_once 'ruta/a/azbox.php';

\Azbox\AZ::Instance(array(
    "api_key" => "TU API KEY", // Tu API key del panel de Azbox
    "projectId" => "TU PROJECT ID", // Tu Project ID del panel de Azbox
    "original_language" => "es", // El idioma original de tu web
    "destination_languages" => "en,fr,de", // Idiomas a los que quieres traducir (separados por comas)
    "buttonOptions" => array(
        "fullname" => true,
        "is_dropdown" => true,
        "position" => "bottom-right",
    ),
));
?>

Ejemplo de Configuración Completa

Aquí tienes un ejemplo más completo con todas las opciones disponibles:

<?php
// Autoload de Composer
require __DIR__ . '/vendor/autoload.php';

\Azbox\AZ::Instance(array(
    "api_key" => "TU API KEY",
    "projectId" => "TU PROJECT ID",
    "original_language" => "es", 
    "destination_languages" => "en,fr,de", 
    "button_position" => "top-right", // Posición del selector de idioma
    "buttonOptions" => array(
        "fullname" => false, // Mostrar código de idioma (ES, FR) en lugar del nombre completo
        "with_name" => true, // Mostrar nombre del idioma en el botón
        "is_dropdown" => true // Usar dropdown en lugar de lista
    ),
    "exclude_blocks" => ".logo,nav #brand", // Selectores CSS para excluir de la traducción
    "exclude_url" => "/terminos-condiciones,/politica-privacidad", // URLs para excluir de la traducción
    "home_url" => "/mi-web" // Subdirectorio si tu sitio no está en la raíz
));
?>

Parámetros de Configuración

Parámetros Requeridos

api_key (string): Tu API key que te da acceso a los servicios de Azbox. Puedes obtener una creando una cuenta en https://panel.azbox.io/register
projectId (string): Tu Project ID del panel de Azbox
original_language (string): El idioma de tu web original. Introduce el código de dos letras (por ejemplo, “es”, “en”, “fr”). Consulta la lista completa de idiomas soportados
destination_languages (string): Los idiomas a los que quieres traducir. Introduce los códigos de dos letras separados por comas (por ejemplo, “en,fr,de”). Consulta la lista completa de idiomas soportados

Parámetros Opcionales

button_position (string, por defecto "bottom-right"): Posición del botón selector de idioma. Opciones:
- "bottom-left" - Esquina inferior izquierda
- "bottom-center" - Centro inferior
- "bottom-right" - Esquina inferior derecha (por defecto)
- "top-left" - Esquina superior izquierda
- "top-center" - Centro superior
- "top-right" - Esquina superior derecha
buttonOptions (array): Un array de parámetros para personalizar el diseño del botón de idioma:
- is_dropdown (bool, por defecto true): true si el botón es una lista desplegable, false para mostrar todos los idiomas como una lista
- with_name (bool, por defecto true): true para mostrar el nombre del idioma en el botón
- fullname (bool, por defecto true): true para mostrar el nombre completo del idioma (Español, Français,…), false para mostrar el código del idioma (ES, FR,…)
exclude_blocks (string, por defecto ""): Lista separada por comas de selectores CSS. Puedes excluir partes de tu web de ser traducidas (por ejemplo, .logo,nav #brand)
exclude_url (string, por defecto ""): Lista separada por comas de URLs relativas. Puedes excluir URLs de tu web de ser traducidas (por ejemplo, /terminos-condiciones,/politica-privacidad)
home_url (string, por defecto ""): Introduce el subdirectorio si tu web no está en la raíz. Por ejemplo, si tu web está en http://localhost/website/, entonces introduce /website

Colocación Personalizada del Botón

Por defecto, el botón de idioma aparece en la posición que especifiques. Sin embargo, también puedes colocar el botón donde quieras en tu página HTML añadiendo este div:

<div id="azbox_here"></div>

Coloca este div donde quieras que aparezca el selector de idioma, y Azbox renderizará el botón ahí en lugar de usar la posición por defecto.

También puedes personalizar la apariencia del botón añadiendo reglas CSS dirigidas a las clases del elemento del botón.

Paso 6: Verificar la Integración

Ahora, cuando visites tu web, deberías ver un botón selector de idioma en la posición especificada (por defecto: esquina inferior derecha).

Verifica el Botón: El selector de idioma debería ser visible en tu web
Prueba el Cambio de Idioma: Haz clic en el botón y selecciona un idioma diferente
Verifica la Traducción: El contenido de tu web debería traducirse automáticamente

Si el botón aparece y el cambio de idioma funciona, ¡tu integración es exitosa!

Paso 7: Gestionar Traducciones

Una vez que tu web está integrada con Azbox, puedes gestionar las traducciones a través del panel de Azbox:

Ver Keywords

Todas las keywords de tu web aparecerán en el panel de tu proyecto. Puedes:

Buscar keywords específicas
Filtrar por categorías
Ver el estado de traducción para cada idioma

Editar Traducciones

Haz clic en una keyword para expandirla
Haz clic en el botón Translate
Revisa y edita las traducciones automáticas
Añade traducciones manuales si es necesario
Asigna categorías para organizar keywords

Optimización de Rendimiento

Azbox almacena automáticamente las traducciones en caché en los navegadores de tus visitantes para proporcionar un cambio de idioma más rápido. Una vez que una página está traducida, los cambios de idioma posteriores serán instantáneos sin necesidad de recargar desde el servidor. Esto mejora la experiencia del usuario y reduce la carga del servidor.

Beneficios del Caché

Cambio de Idioma Más Rápido: Las traducciones se almacenan en caché localmente
Menor Carga del Servidor: Se necesitan menos llamadas API
Mejor Experiencia de Usuario: Cambios de idioma instantáneos
Soporte Offline: Las traducciones en caché funcionan offline

Solución de Problemas

El Botón No Aparece

Si el botón de idioma no aparece en tu web:

Verifica Errores de PHP: Asegúrate de que no hay errores de PHP en tu log de errores
Verifica la API Key: Asegúrate de que tu API key es correcta
Verifica el Project ID: Verifica que tu Project ID es correcto
Orden de Inicialización: Asegúrate de que el código de inicialización de Azbox se ejecuta antes de cualquier salida HTML
Rutas de Archivos: Verifica que los archivos de la librería Azbox están en la ubicación correcta

Errores 404 al Cambiar de Idioma

Si ves errores 404 o “Not found” al cambiar de idioma:

Ubicación de Inicialización: El código de Azbox debe ejecutarse al principio de tu código PHP, antes de cualquier procesamiento de solicitud
Reglas de Rewrite: Asegúrate de que las reglas de rewrite de tu servidor web están configuradas para que el código PHP se ejecute en páginas 404
Revisa los Logs de Errores: Revisa tus logs de errores de PHP y del servidor web para detectar problemas

Las Traducciones No Funcionan

Si las traducciones no aparecen:

Verifica Keywords: Comprueba que las keywords existen en tu proyecto Azbox
Configuración de Idioma: Asegúrate de que los idiomas de destino coinciden con la configuración de tu proyecto
Problemas de Caché: Limpia la caché de tu navegador e inténtalo de nuevo
Conexión API: Verifica que tu API key tiene los permisos adecuados

¿Sigues Teniendo Problemas?

Si sigues experimentando problemas:

Contacta con el soporte de Azbox en support@azbox.io
Usa el chat en vivo en el sitio web de Azbox
Consulta la documentación de Azbox PHP
Revisa el repositorio de GitHub para ver ejemplos

Mejores Prácticas

Seguridad

Nunca subas API keys al control de versiones
Usa variables de entorno o archivos de configuración fuera de la raíz web
Restringe los permisos de la API key en tu panel de Azbox

Organización

Usa categorías para organizar keywords por página o sección
Nombra keywords descriptivamente para facilitar la gestión
Revisa traducciones automáticas antes de publicar

Rendimiento

Excluye elementos innecesarios de la traducción usando exclude_blocks
El caché de traducciones se gestiona automáticamente por Azbox
Monitoriza el uso de API en tu panel de Azbox

Mantenimiento

Revisa regularmente las traducciones para verificar su precisión
Actualiza keywords cuando cambie el contenido
Prueba el cambio de idioma después de actualizaciones importantes

Ejemplo: Configuración Completa Funcionando

Aquí tienes un ejemplo completo de una página PHP simple con Azbox integrado:

index.php:

<?php
// Inicializa Azbox al principio
require __DIR__ . '/vendor/autoload.php';

\Azbox\AZ::Instance(array(
    "api_key" => "TU_API_KEY",
    "projectId" => "TU_PROJECT_ID",
    "original_language" => "es",
    "destination_languages" => "en,fr,de",
    "button_position" => "bottom-right",
    "buttonOptions" => array(
        "fullname" => true,
        "is_dropdown" => true,
    ),
));
?>
<!DOCTYPE html>
<html lang="es">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Mi Web</title>
</head>
<body>
    <header>
        <h1>Bienvenido a Mi Web</h1>
        <nav>
            <a href="/">Inicio</a>
            <a href="/acerca-de">Acerca de</a>
            <a href="/contacto">Contacto</a>
        </nav>
    </header>
    
    <main>
        <section>
            <h2>Sobre Nosotros</h2>
            <p>Esta es una web de ejemplo que demuestra la integración de Azbox.</p>
        </section>
        
        <section>
            <h2>Nuestros Servicios</h2>
            <ul>
                <li>Desarrollo Web</li>
                <li>Servicios de Traducción</li>
                <li>Consultoría</li>
            </ul>
        </section>
    </main>
    
    <footer>
        <p>&copy; 2025 Mi Web. Todos los derechos reservados.</p>
    </footer>
</body>
</html>

Este ejemplo demuestra:

Inicialización correcta de Azbox al principio
Estructura HTML simple que será traducida automáticamente
Botón selector de idioma en la esquina inferior derecha (posición por defecto)

Recursos Adicionales

Conclusión

Integrar Azbox en tu web PHP es sencillo y proporciona capacidades potentes de gestión de traducciones. Siguiendo esta guía, puedes:

Configurar un proyecto web en Azbox
Importar keywords existentes de tu web
Instalar y configurar la librería Azbox PHP
Gestionar traducciones a través del panel de Azbox
Proporcionar una experiencia multilingüe fluida para tus usuarios

Las características de traducción automática y caché hacen que sea fácil soportar múltiples idiomas sin una sobrecarga significativa de desarrollo. ¡Comienza a traducir tu web PHP hoy y llega a una audiencia global!

Cómo Traducir una Web PHP con Azbox: Guía Completa