PHP Hello World with Tolgee Translation

A simple PHP project that demonstrates integration with the Tolgee translation API and invisible text encoding, running in Docker.

Project Structure

• index.php: A PHP file that displays "Hello, World!", translation examples, and invisible encoding examples
• Translator.php: A class that handles translation using the Tolgee API
• InvisibleWrapper.php: A class that wraps text with invisible Unicode characters
• Dockerfile: Configuration for building a Docker image with PHP and Apache
• docker-compose.yml: Configuration for running the Docker container

Requirements

• Docker
• Docker Compose

How to Run

1. Clone this repository
2. Navigate to the project directory
3. Set up your Tolgee API key using one of the methods described in the Tolgee API Configuration section
   • For quick setup, copy the .env.example file to .env and add your API key
4. Run the following command:

docker-compose up -d

5. Open your browser and go to http://localhost:8999
6. You should see the translation examples displayed in your browser

How to Stop

To stop the Docker container, run:

docker-compose down

Development

The project is set up with a volume mount, so any changes you make to the PHP files will be immediately reflected when you refresh the browser.

Tolgee Development Mode

Tolgee is configured to run in development mode, which enables features like in-context translation editing and key highlighting. Development mode is enabled by:

1. Using the development version of the Tolgee JavaScript SDK:

<script src="https://cdn.jsdelivr.net/npm/@tolgee/web/dist/tolgee-web.development.umd.js"></script>

2. Setting the development parameter to true in the JavaScript configuration:

const tolgee = Tolgee()
  .use(DevTools())
  .use(ObserverPlugin())
  .use(DevBackend())
  .init({
    // other configuration...
    development: true
  })

3. Setting the mode parameter to 'development' in the PHP configuration:

$config = [
  // other configuration...
  'mode' => 'development'
];

When development mode is enabled, the Translator class will wrap translations with invisible encoded key data, which allows the Tolgee JavaScript SDK to identify and highlight translation keys in the browser.

Tolgee API Configuration

This project uses the Tolgee translation management platform. To configure the Tolgee API integration:

1. Sign up for a Tolgee account at https://app.tolgee.io/sign_up
2. Create a new project
3. (optional) Add some keys for testing
4. Generate an API key with read permissions for your project
5. Set your API key as an environment variable:

Option 1: Using docker-compose.yml

Uncomment and update the environment variable in docker-compose.yml:

environment:
  TOLGEE_API_KEY: your_api_key_here

Option 2: Setting environment variable directly

You can also set the environment variable before running the application:

# Linux/macOS
export TOLGEE_API_KEY=your_api_key_here
docker-compose up -d

# Windows (Command Prompt)
set TOLGEE_API_KEY=your_api_key_here
docker-compose up -d

# Windows (PowerShell)
$env:TOLGEE_API_KEY="your_api_key_here"
docker-compose up -d

Option 3: Using a .env file (recommended for development)

Copy the provided .env.example file to create your own .env file:

cp .env.example .env

Then edit the .env file to add your actual API key:

TOLGEE_API_KEY=your_api_key_here

The docker-compose.yml file is already configured to use the .env file:

environment:
  TOLGEE_API_KEY: ${TOLGEE_API_KEY}

Note: The .env file is included in .gitignore to prevent accidentally committing your API key to the repository.

The Translator class will automatically fetch translations from the Tolgee API when needed.

API Response Format

The Tolgee API is expected to return translations in the following format:

{
  "en": {
    "what a key": "Translated value",
    "another key": "Another key translated"
  },
  "cs": {
    "what a key": "Překlad",
    "another key": "Další překlad"
  }
}

Where:

• The top-level keys are language codes
• Each language contains key-value pairs of translation keys and their translated values
• The Translator class will use the translations for the language specified in the configuration

Invisible Wrapper

The project includes an InvisibleWrapper class that can wrap text with invisible Unicode characters. This can be useful for:

• Embedding metadata in HTML without affecting the visual appearance
• Creating watermarks in text content
• Implementing steganography techniques in web pages
• Tracking the origin of copied content

How It Works

The wrapper uses two special Unicode characters (Zero-Width Non-Joiner and Zero-Width Joiner) that are invisible when rendered in browsers. The wrapping process:

1. Converts the input text to bytes
2. Converts each byte to an 8-bit binary representation
3. Adds a separator bit after each byte
4. Maps each bit to one of the invisible characters
5. Appends the invisible characters to the original text

Usage Example

// Include the class
require_once 'InvisibleWrapper.php';

// Create an instance
$encoder = new InvisibleWrapper();

// Encode a message
$message = "Hello, World!";
$encodedMessage = $encoder->encodeMessage($message);

// The encoded message can be added to any HTML element
echo "<p>This text contains invisible data" . $encodedMessage . "</p>";

The encoded message is completely invisible when rendered in a browser but can be detected and decoded by JavaScript or other tools.