DEV Community: Hugo Bernardo Cardoso

From Zero to Production: Building a Secure OG Image API

Hugo Bernardo Cardoso — Tue, 18 Aug 2026 08:22:57 +0000

From Zero to Production: Building a Secure OG Image API

Every time you paste a link into Slack, WhatsApp, or X, a tiny war is being fought. The social platform's crawler hits your page, reads the Open Graph tags, and decides what to show. If your og:image is missing, slow, or ugly, your link becomes a bare URL. No thumbnail. No headline. No click.

For most developers, the fix is a static image. But static images don't scale when you're generating a unique preview for every product page, blog post, or pricing tier. You need dynamic OG images — and you need them served securely, at speed, without melting your server budget.

This is the story of building exactly that: a production-grade OG image API with HMAC-signed URLs, headless Chrome rendering, and edge caching that makes the first request the only expensive one.

The Problem: Why Your Previews Fail

Client-side OG image generation is a trap. Social network crawlers — LinkedIn, Twitter, Facebook — don't execute JavaScript. They fetch your URL, read the raw HTML, and move on. If your og:image is generated client-side, the crawler sees nothing.

Server-side generation fixes this, but introduces its own problems. Rendering a 1200×630 image on every request is expensive. A naive implementation using a headless browser per request will eat CPU, exhaust memory, and time out under load.

The solution is a dedicated API that separates rendering from serving. You pay for the render once, cache the result aggressively, and let the edge handle the rest.

The Architecture: Three Moving Parts

FastOG's approach breaks down into three components that work together:

A signed URL layer — every request carries an HMAC-SHA256 signature so only authorized callers can trigger renders
A render service — headless Chrome (via Browsershot) renders Svelte 5 templates at exactly 1200×630
A caching layer — successful renders are cached for a year with Cache-Control: public, max-age=31536000, immutable

The signing layer is the part most people get wrong. You might be tempted to put your API key in a header. That works for your own server-side code, but it breaks the moment a social network crawler tries to fetch the image. Crawlers don't send custom headers. They just fetch the URL.

That's why signatures live in the URL itself.

URL-Signed Security: The HMAC Pattern

Here's the core endpoint:

GET /api/v1/og?key=YOUR_API_KEY&s=SIGNATURE&title=Hello&template=blog

The signature is computed by taking the canonical sorted query string, RFC 3986-encoding it, and HMAC-ing it with your secret key. Every API key has its own secret.

A minimal Node.js signer looks like this:

import crypto from 'crypto';

function sign(params, secret) {
  const canonical = Object.keys(params)
    .filter(k => k !== 's')
    .sort()
    .map(k => `${k}=${encodeURIComponent(params[k])}`)
    .join('&');

  const signature = crypto
    .createHmac('sha256', secret)
    .update(canonical)
    .digest('hex');

  return `${canonical}&s=${signature}`;
}

const params = {
  key: 'your_api_key',
  title: 'How to Build an OG Image API',
  template: 'devblog'
};

const url = `https://fastog.com/api/v1/og?${sign(params, 'your_secret')}`;

The signature goes in the URL because that's the only thing crawlers will faithfully transmit. It's a deliberate trade-off: you accept that signatures are visible in logs in exchange for images that work everywhere.

Rendering: Why Satori Isn't Enough

You can generate OG images without a browser. Libraries like Satori render JSX to SVG, then you convert to PNG. It's fast and lightweight. But it has limits: no complex CSS, no web fonts, no JavaScript.

When you need 41 different templates — ecommerce cards with prices and ratings, podcast episodes with progress bars, countdown timers for launches — a real browser becomes the pragmatic choice.

FastOG runs a separate Node render service that receives render jobs and drives headless Chrome via Browsershot. The service has a self-healing watchdog: a health check endpoint that auto-restarts the Docker container if it wedges. This matters because headless Chrome will wedge. It's not a question of if, but when.

The render service is separate from the API for a reason. If Chrome crashes, the API stays up. If the API is under load, renders queue gracefully. You don't want a browser crash taking down your whole endpoint.

Credit Economics: Deduct Only on Success

The billing model is simple: each render costs 1 credit. But the important detail is when credits are deducted.

Deduction happens only after a successful render, protected by an atomic lock to prevent double-spending. If the render fails — invalid parameters, render service unreachable, rate limit exceeded — you get a machine-readable error code (insufficient_credits, render_unreachable) and your credits stay untouched.

The response headers tell you where you stand:

X-Renders-Remaining: 42
X-FastOG-Watermark: false

This matters for production systems. You can build retry logic around 502 and 503 responses without worrying about being charged for failed attempts.

Caching: The First Request Is the Only Expensive One

Here's the economics that make this viable: the first request for a given set of parameters triggers a render. That render costs 1 credit. Every subsequent request for the same URL — from LinkedIn's crawler, from Slack's unfurler, from a user's browser — hits the cache.

The Cache-Control: public, max-age=31536000, immutable header tells every intermediary (CDN, browser, crawler) to hold onto the image for a year. Your cost per image approaches zero as the image gets shared more.

This is the pattern that makes dynamic OG images practical at scale. You're not paying per impression; you're paying per unique image.

From Zero to Production: The Checklist

If you're building your own OG image service, here's the minimum viable architecture:

Sign every request — HMAC-SHA256 in the URL, not headers
Separate rendering from serving — a crash in Chrome shouldn't take down your API
Cache aggressively — immutable cache headers, long max-age
Deduct credits only on success — atomic locks, machine-readable errors
Add a health check — headless Chrome will crash; plan for it

FastOG implements all of this out of the box. You get 100 free credits on signup, credit packs start at $2, and there's a free OG Image Tester that requires no account at all — you can preview templates and download a real PNG client-side before committing to anything.

The free tester is the fastest way to understand what you're buying. Paste your title, pick a template, see exactly what LinkedIn will display. No signup, no credit card, no friction.

The Bottom Line

Dynamic OG images are a competitive advantage. A link with a well-designed preview gets clicked; a bare URL gets scrolled past. The technical challenge is making generation secure, reliable, and affordable.

URL-signed HMAC authentication solves the crawler problem. A dedicated render service with a watchdog solves the reliability problem. Year-long immutable caching solves the cost problem.

The result is an API where the first request costs one credit and everything after is free — and that's a trade worth making.

How to Implement Dynamic OG Images in Next.js, Remix, or Laravel: A Step-by-Step Guide

Hugo Bernardo Cardoso — Mon, 17 Aug 2026 08:25:40 +0000

How to Implement Dynamic OG Images in Next.js, Remix, or Laravel: A Step-by-Step Guide

Why Your Static OG Image Is Costing You Clicks

When you share a link on LinkedIn, X, Slack, WhatsApp, or Facebook, the platform crawls your page and pulls the og:image meta tag. If that image is static — the same generic banner for every URL — you're leaving clicks on the table.

Here's the problem: a static OG image says nothing about what the reader will get. "How to Implement Dynamic OG Images" with a generic gradient tells me nothing. "How to Implement Dynamic OG Images — 7 Steps, 15 Minutes, Zero Server Setup" tells me everything. The latter gets the click.

Dynamic OG images — generated per-URL with the actual title, author, price, or rating baked in — convert better because they set accurate expectations. The crawler sees a preview that matches the content, so the person on the other end knows exactly what they're opening.

But here's the catch: social crawlers don't execute JavaScript. Client-side rendering fails silently. WhatsApp, Twitter, and LinkedIn all fetch your URL server-side and read the raw HTML. If your OG image is generated client-side, you get a blank preview or a broken image.

The fix is a server-side endpoint that returns a real image. FastOG does exactly this: you call one URL with query parameters, and you get back a ready-to-share 1200×630 PNG, JPEG, or WebP — rendered server-side by headless Chrome, not assembled client-side.

Prerequisites: What You Need Before You Start

Before you wire anything up, you need:

A FastOG account — you get 100 free credits on signup, no credit card required
Your API key and secret — found in your dashboard; each key has its own HMAC secret
A framework — Next.js (App or Pages Router), Remix, or Laravel; the pattern is identical across all three
A template ID — FastOG ships 41 server-side Svelte 5 templates (blog, product, pricing, saaslaunch, stats, bento, comparison, countdown, promo, ecommerce, game, news, podcast, video, devblog, codepost, and more)

The core endpoint is GET /api/v1/og. Each render costs 1 credit, and the image is cached for a year (Cache-Control: public, max-age=31536000, immutable), so everyone after the first request gets it for free.

Step 1: Set Up Your Dynamic Image Endpoint

The pattern is the same in every framework: accept the incoming request, build the OG image URL with your parameters, sign it, and return it as the og:image meta tag.

Here's the canonical flow in Laravel:

// routes/web.php
Route::get('/post/{slug}', function ($slug) {
    $post = Post::where('slug', $slug)->firstOrFail();

    $ogUrl = 'https://api.fastog.com/api/v1/og?' . http_build_query([
        'template' => 'blog',
        'title' => $post->title,
        'subtitle' => $post->excerpt,
        'author' => $post->author_name,
        'key' => config('services.fastog.key'),
        's' => sign_og_url($post), // see Step 4
    ]);

    return view('post', [
        'post' => $post,
        'ogImage' => $ogUrl,
    ]);
});

In Next.js App Router, you'd do the same inside a generateMetadata function:

// app/post/[slug]/page.tsx
export async function generateMetadata({ params }): Promise<Metadata> {
  const post = await getPost(params.slug);
  const ogUrl = buildOgUrl({
    template: 'blog',
    title: post.title,
    subtitle: post.excerpt,
    author: post.author_name,
  });

  return {
    title: post.title,
    openGraph: {
      images: [{ url: ogUrl, width: 1200, height: 630 }],
    },
  };
}

And in Remix, inside a loader or meta export:

export const meta: MetaFunction = ({ data }) => {
  return [
    { title: data.post.title },
    { property: 'og:image', content: buildOgUrl(data.post) },
  ];
};

The key insight: the OG image URL is just a URL. Any framework that can emit a <meta> tag can use it.

Step 2: Design Your Template and Pass Data Safely

FastOG renders templates server-side with Svelte 5 at exactly 1200×630 using headless Chrome (Browsershot) in a separate Node render service. You don't touch the rendering pipeline — you just pass data.

The available query parameters are: title, subtitle, template, price, original_price, rating, features, badge, image, and more, depending on the template.

Security rule: treat the OG URL as untrusted input. Never pass raw user content without encoding. FastOG signs the canonical sorted query with RFC 3986 encoding, so the signature covers every parameter. If you're building the URL yourself, use URLSearchParams or http_build_query — don't hand-concatenate strings.

A safe pattern:

function buildOgUrl(params: Record<string, string>): string {
  const search = new URLSearchParams({
    ...params,
    key: process.env.FASTOG_KEY!,
  });
  search.set('s', sign(params)); // HMAC signature
  return `https://api.fastog.com/api/v1/og?${search.toString()}`;
}

Step 3: Handle Caching and Edge Storage

This is where FastOG's economics get interesting. Every render costs 1 credit, but the image is cached for a year. The first request for a given URL pays the credit; everyone after that gets the cached copy for free.

The response includes Cache-Control: public, max-age=31536000, immutable. That means:

Social crawlers (LinkedIn, Twitter, Facebook) hit the cached copy — fast, no credit cost
Your users sharing the link also hit the cache
You don't pay for repeat renders

If you're generating OG images for a high-traffic site, this is the difference between $0.0014 per image and effectively $0 after the first render.

Step 4: Add HMAC Signing for Security

This is the part most tutorials skip, and it's the one that matters. FastOG requires every request to carry key + s (signature). The signature lives in the URL, not in headers, because social network crawlers don't send custom headers.

The signing algorithm:

Take all query parameters except s
Sort them alphabetically by key
RFC 3986-encode each key and value
Concatenate as key=value&key=value
HMAC-SHA256 the result with your API secret

Here's a working implementation in Node.js:

import crypto from 'crypto';

export function signOgUrl(params: Record<string, string>, secret: string): string {
  const sorted = Object.keys(params)
    .filter(k => k !== 's')
    .sort()
    .map(k => `${encodeURIComponent(k)}=${encodeURIComponent(params[k])}`)
    .join('&');

  return crypto.createHmac('sha256', secret).update(sorted).digest('hex');
}

And in PHP:

function signOgUrl(array $params, string $secret): string {
    ksort($params);
    $canonical = http_build_query($params, '', '&', PHP_QUERY_RFC3986);
    return hash_hmac('sha256', $canonical, $secret);
}

Why bother? Because without signing, anyone can burn your credits by hitting your endpoint with arbitrary parameters. With signing, only requests you authorized render.

Step 5: Test Across All Major Platforms

Different platforms cache OG images differently. Here's what to check:

LinkedIn: notoriously aggressive caching. Use their Post Inspector to force a refresh.
X (Twitter): use the Card Validator. It shows you exactly what the crawler sees.
WhatsApp: the most frustrating — it caches aggressively and has no public debugger. Append ?v=2 to your URL to bust the cache.
Facebook: the Sharing Debugger lets you scrape fresh and see errors.

FastOG also has a free OG Image Tester — no signup required — that previews your image client-side and downloads a real PNG. It's the fastest way to sanity-check a template before you deploy.

Step 6: Go Live with Monitoring and Analytics

Once you're live, watch these signals:

X-Renders-Remaining header on every response — tells you your credit balance
X-FastOG-Watermark header — confirms whether the image is watermarked
Error codes — 402 (insufficient credits), 422 (validation error), 502 (render service unreachable), 503 (service unavailable). Errors cost nothing — deduction happens only after a successful render, with an atomic lock preventing double-spend.

If you see a spike in 502s, the render service may have wedged. FastOG runs a self-healing watchdog (og:health) that auto-restarts the Docker container, but you should still monitor your error rate.

Troubleshooting Common Issues: Empty Previews, Caching, and Quotas

"My preview is blank on WhatsApp but works on X" — WhatsApp caches aggressively and doesn't honor cache-busting headers. Append a query param (?v=timestamp) to force a fresh fetch.

"The image is stale on LinkedIn" — Use LinkedIn's Post Inspector to force a re-scrape. It's the only reliable way.

"I'm out of credits" — Check X-Renders-Remaining. Cached images are free, so the fix is usually to ensure your cache headers are being respected. If you're genuinely out, credit packs start at $2.

"My signature doesn't validate" — The most common cause is encoding mismatch. Make sure you're using RFC 3986 encoding (not encodeURIComponent's default) and that your parameters are sorted before signing.

"I'm getting 422s" — You're passing an invalid parameter or template name. Check the template list and your parameter names against the API reference.

Dynamic OG images are a small change with an outsized impact on click-through. The pattern is identical whether you're on Next.js, Remix, or Laravel: build a signed URL, emit it as og:image, and let the server-side renderer do the work. FastOG handles the rendering, caching, and security — you just ship the meta tag.

Android Strings XML Translation Online: The No-Login Tool That Preserves Your Variables

Hugo Bernardo Cardoso — Sun, 16 Aug 2026 09:56:57 +0000

Android Strings XML Translation Online: The No-Login Tool That Preserves Your Variables

You're solo. You're shipping in weeks. Your strings.xml file has 1,200 lines, and 14 of them contain %1$s or {player_name} placeholders that will crash your app if a translator touches them.

Agencies want $2,000 and three weeks. ChatGPT mangles your variable tags, skips long strings, and you're stuck fixing broken JSON at 2 AM.

LocaFile AI is the android strings XML translation online tool built for exactly this moment. No login. No subscription. No per-word haggling. You upload your file, pay a flat fee, and get a ZIP back with every string translated and every variable locked in place.

What LocaFile AI Actually Does

LocaFile AI is a no-login, pay-per-pass AI game localization web app. It's built for solo developers and small indie studios shipping on Steam — the people who need 8 languages for a Steam Next Fest demo but don't have a localization budget.

The core flow is dead simple:

Upload — drag and drop your game string file. The parser detects the format, counts words, and validates structure. No account required.
Preview for free — paste a few lines and run a free syntax check. You can even test a real AI translation pass on up to 5 lines before paying anything.
Pay once — a flat fee via Stripe. You get an entitlement token, not a user account.
Get your ZIP — the translation job runs through a three-pass AI pipeline, bundles everything, and delivers it via on-screen download plus email.

The entire process takes minutes, not weeks.

The Variable Problem: Why Most Translation Tools Break Your Game

Here's the thing nobody tells you about android string translation: it's not the words that break your app. It's the variables.

Your strings.xml probably contains entries like this:

<string name="welcome_message">Welcome back, %1$s! You have {unread_count} new messages.</string>
<string name="health_display"><color=red>HP:</color> {current_hp}/{max_hp}</string>

A generic translation service sees %1$s, {unread_count}, and <color=red> as text to translate. It "helpfully" rewrites them, reorders them, or drops them entirely. The result? Your app crashes on launch, or worse, displays [[MISSING]] placeholders to players in 8 languages.

This is the problem LocaFile AI was built to solve. The core differentiator is a VariableLocker system with 10 variable-matcher presets: double_curly, dollar_curly, single_curly, square_bracket, smart_string, printf, rich_text, laravel_colon, button_glyph, and subtitle_tag.

Before the AI ever sees your text, every variable is swapped for a [[LOCK_N]] token:

Before: "Welcome back, %1$s! You have {unread_count} new messages."
After:   "Welcome back, [[LOCK_1]]! You have [[LOCK_2]] new messages."

The AI translates the surrounding text. Then the locker restores your variables byte-for-byte. A validator checks every single one. You get a per-language QA report proving nothing was mangled.

This matters for every format, not just Android. The same engine handles Godot CSV/TSV/PO files, Unity CSV/YAML/JSON, Ren'Py scripts, Unreal projects, Flutter ARB files, and subtitle formats like SRT, VTT, ASS, and SBV. The android strings.xml translation online workflow is just one of 17 format parsers under the hood.

The Android Strings XML Translation Workflow

Let's walk through the actual android translate strings.xml process.

Step 1: Upload and Analyze

Go to locafileai.com, drag your strings.xml onto the upload zone. The parser detects the format, validates the XML structure, counts words, and gives you a price. No signup form. No "create an account to see pricing" wall.

If you're not sure whether your file is valid, paste a snippet into the free syntax checker at /analyze. It'll flag malformed XML, duplicate keys, or unescaped quotes before you spend a cent.

Step 2: Free Preview

This is where LocaFile AI differs from every android string translation tool that makes you pay upfront and pray. You can lock variables on your pasted string with zero AI cost, then run one real AI pass on up to 5 lines. You'll see exactly how the variable locking works before you commit.

The preview is throttled at 10 requests per minute because every AI call costs money — but for a 5-line test, you'll never hit that limit.

Step 3: Pay and Translate

Pick your tier. The Indie Starter at $19 is an impulse buy for solo devs prepping a Steam Next Fest demo. The Steam Launchpad at $99 fits small studios shipping a full launch. The Studio Pass at $249 covers multi-SKU and DLC workflows.

Pay through Stripe Checkout. The webhook creates your entitlement — a UUID, not a user account — and dispatches the translation job.

Step 4: The Three-Pass Pipeline

Your file doesn't get one pass through an AI model. It gets three:

Pass one locks all variables and does the initial translation.
Pass two reviews for consistency, context, and tone.
Pass three validates every variable was restored correctly and runs quality checks.

Each language gets a TranslationQaReport. If a variable was dropped, the pipeline catches it before you ever download the file.

Step 5: Download and Ship

You get a ZIP with all your translated strings.xml files, organized by locale. The download link expires after 24 hours, but you'll also get the files via email. Lose the link? The /recover endpoint regenerates it from your UUID.

If a job fails partway through, you can retry without re-paying — the pipeline resumes from the completed languages instead of starting over.

Why This Beats the Alternatives

Agencies deliver quality but cost $2,000+ and take weeks. You don't have weeks.

Raw ChatGPT is free but will mangle your {player_name} tags, skip long strings, and produce inconsistent terminology across 8 languages. You'll spend more time fixing broken XML than you saved.

Other online tools treat translation as a text swap. They don't understand game string formats, variable placeholders, or the difference between %1$s and %s.

LocaFile AI is the android strings xml translation tool that treats your variables as inviolable. The entire architecture — the VariableLocker, the three-pass pipeline, the QA reports — exists to guarantee one thing: your app won't crash when translated.

The Bottom Line

If you're a solo dev or small studio shipping on Steam, you need android strings XML translation online that doesn't require an account, doesn't charge per word, and won't break your game. LocaFile AI delivers exactly that: upload, pay a flat fee, download your ZIP, ship your game.

No login. No subscription. No fixing broken tags at 2 AM.

How to Generate OG Images at Scale: A Developer's Guide

Hugo Bernardo Cardoso — Sat, 15 Aug 2026 14:55:45 +0000

How to Generate OG Images at Scale: A Developer's Guide

The link preview is the first thing people see before they click. On X, LinkedIn, Slack, and iMessage, your URL renders as a 1200×630 card — and if that card is a generic gray box with your domain name, you've already lost the click to the person who posted a screenshot instead.

Dynamic Open Graph images fix this. Instead of one static PNG per page, you render a unique card per URL — title, author, reading time, a chart, whatever your page actually contains. The result is a measurable lift in click-through rate and share velocity. But how you generate those images matters more than whether you do it at all. Get the architecture wrong and you'll ship broken cards, burn server resources, or lock yourself into a tool that can't scale.

Here's the landscape, the trade-offs, and a pipeline that holds up under real traffic.

The Landscape: Client-Side vs. Server-Side Rendering

Client-side generation is the trap. Tools like myogimage.com let you design a template in the browser and export a static PNG. That's fine for a one-off — but it collapses the moment you need dynamic content. You can't render a card for a blog post that doesn't exist yet, and you can't automate a pipeline around a GUI. Worse, some of these "free" tools advertise an API that doesn't actually exist. If your OG strategy depends on a service that can't be called programmatically, you don't have a strategy — you have a screenshot.

The other client-side trap is generating images in the browser at request time. Social scrapers (Twitterbot, Slackbot, LinkedInBot) don't execute JavaScript. If your OG image is rendered client-side, the scraper sees nothing. This is the single most common reason "my OG image works in the preview but not when I share it."

Server-side rendering is the only approach that works reliably. The scraper makes a GET request, your server returns a complete PNG. No JavaScript required. Within server-side, you have two real options:

DIY with satori + a deployment platform (the Vercel approach). satori converts JSX to SVG, then you rasterize to PNG with resvg or sharp. It's fast, it's free, and it's fully under your control. The cost is yours too: you maintain the rendering service, handle font loading, manage concurrency, and debug edge cases yourself. It's a solid choice if you have the time and the traffic justifies the infrastructure.
A dedicated OG image API (like FastOG). You send a GET request with your template and parameters, the service renders the image server-side, caches it at the edge, and returns a URL. No infrastructure to maintain, no fonts to bundle, no scraper compatibility to test. You pay per image, and caching means repeat renders cost nothing.

The right choice depends on your constraints. If you're an indie hacker shipping a blog this weekend, the DIY stack is a fun afternoon project. If you're building a SaaS where every page needs a unique card and your time is better spent on the product, a managed API wins.

Anatomy of a High-Performance OG Image Pipeline

A production-grade pipeline has five stages. Here's what each one needs to do.

1. URL Design

Your OG image endpoint should be a simple GET request with query parameters — no auth headers, no POST bodies. Social scrapers only send GET requests. FastOG's pattern looks like this:

https://api.fastog.com/api/v1/og?template=blog&title=Hello%20World&author=Jane

Keep the parameter surface small. Every parameter is a template variable you need to document, validate, and test. Start with 3–5 per template.

2. Template Registry

A template is a design with named slots: title, author, date, reading_time, accent_color. Your registry maps a template ID to its layout and default styles. FastOG ships 41 templates covering OG cards (1200×630) and X headers (1500×500) — but you don't need 41. You need a handful that match your brand and a registry that makes adding new ones trivial.

3. Rendering

The renderer takes the template, injects the parameters, and produces a PNG. This is where satori-style approaches and managed APIs diverge. The key performance metric is time-to-first-byte: social scrapers are impatient. If your render takes longer than ~2 seconds, platforms will fall back to a generic card. FastOG renders via Svelte → headless Chrome, which handles complex layouts and custom fonts gracefully, and serves the result from edge cache.

4. Caching

This is the difference between "paying per image" and "paying per unique image." If your pipeline caches at the CDN edge, the first render of a URL is the only render that costs anything. Every subsequent scrape — and there will be many, every time someone shares the link — hits the cache. FastOG's model is 1 credit = 1 image, with 0 cost on cache hits. If you're DIY, make sure your cache layer is in front of your renderer, not behind it.

5. Security

If your OG endpoint accepts query parameters, it's a public URL. Anyone can hit it. That's fine for public content, but it means you need HMAC signing for anything you don't want rendered arbitrarily. The pattern:

// Node.js example: sign an OG image URL
const crypto = require('crypto');

function signOgUrl(baseUrl, params, secret) {
  const query = new URLSearchParams(params).toString();
  const signature = crypto
    .createHmac('sha256', secret)
    .update(query)
    .digest('hex');
  return `${baseUrl}?${query}&sig=${signature}`;
}

// Usage
const url = signOgUrl(
  'https://api.fastog.com/api/v1/og',
  { template: 'blog', title: 'Hello World' },
  process.env.OG_SECRET
);

The server recomputes the HMAC and rejects requests with an invalid or missing signature. This prevents abuse of your render quota and stops people from generating arbitrary images on your dime.

Putting It Together

Here's a minimal implementation for a blog, using a managed API:

// lib/og.js
const OG_BASE = 'https://api.fastog.com/api/v1/og';
const OG_SECRET = process.env.OG_SECRET;

export function getOgImageUrl({ title, excerpt, slug }) {
  const params = {
    template: 'blog',
    title,
    excerpt,
    slug,
  };
  const query = new URLSearchParams(params).toString();
  const sig = crypto.createHmac('sha256', OG_SECRET).update(query).digest('hex');
  return `${OG_BASE}?${query}&sig=${sig}`;
}

Then in your page template, add the meta tags:

<meta property="og:title" content={title} />
<meta property="og:image" content={getOgImageUrl({ title, excerpt, slug })} />

That's it. The scraper fetches the image URL, your API renders and caches it, and every share of that page shows a custom card.

The Bottom Line

Client-side OG tools are fine for a static site with five pages. The moment you need dynamic cards — per-post, per-user, per-product — you need a server-side pipeline. Whether you build it with satori or buy it from a managed API depends on your time budget and traffic. But the architecture is non-negotiable: GET-based URL, template registry, fast renderer, edge cache, and HMAC signing.

Start with one template and one page type. Measure your click-through rate before and after. When you see the lift, expand to the rest of your site. The first card is the hardest — everything after that is just filling in the template.

How to Generate OG Images at Scale: A Developer's Guide

Hugo Bernardo Cardoso — Sat, 15 Aug 2026 14:52:36 +0000

How to Generate OG Images at Scale: A Developer's Guide

Here's the landscape, the trade-offs, and a pipeline that holds up under real traffic.

The Landscape: Client-Side vs. Server-Side Rendering

DIY with satori + a deployment platform (the Vercel approach). satori converts JSX to SVG, then you rasterize to PNG with resvg or sharp. It's fast, it's free, and it's fully under your control. The cost is yours too: you maintain the rendering service, handle font loading, manage concurrency, and debug edge cases yourself. It's a solid choice if you have the time and the traffic justifies the infrastructure.
A dedicated OG image API (like FastOG). You send a GET request with your template and parameters, the service renders the image server-side, caches it at the edge, and returns a URL. No infrastructure to maintain, no fonts to bundle, no scraper compatibility to test. You pay per image, and caching means repeat renders cost nothing.

Anatomy of a High-Performance OG Image Pipeline

A production-grade pipeline has five stages. Here's what each one needs to do.

1. URL Design

Your OG image endpoint should be a simple GET request with query parameters — no auth headers, no POST bodies. Social scrapers only send GET requests. FastOG's pattern looks like this:

https://api.fastog.com/api/v1/og?template=blog&title=Hello%20World&author=Jane

Keep the parameter surface small. Every parameter is a template variable you need to document, validate, and test. Start with 3–5 per template.

2. Template Registry

3. Rendering

4. Caching

5. Security

// Node.js example: sign an OG image URL
const crypto = require('crypto');

function signOgUrl(baseUrl, params, secret) {
  const query = new URLSearchParams(params).toString();
  const signature = crypto
    .createHmac('sha256', secret)
    .update(query)
    .digest('hex');
  return `${baseUrl}?${query}&sig=${signature}`;
}

// Usage
const url = signOgUrl(
  'https://api.fastog.com/api/v1/og',
  { template: 'blog', title: 'Hello World' },
  process.env.OG_SECRET
);

The server recomputes the HMAC and rejects requests with an invalid or missing signature. This prevents abuse of your render quota and stops people from generating arbitrary images on your dime.

Putting It Together

Here's a minimal implementation for a blog, using a managed API:

// lib/og.js
const OG_BASE = 'https://api.fastog.com/api/v1/og';
const OG_SECRET = process.env.OG_SECRET;

export function getOgImageUrl({ title, excerpt, slug }) {
  const params = {
    template: 'blog',
    title,
    excerpt,
    slug,
  };
  const query = new URLSearchParams(params).toString();
  const sig = crypto.createHmac('sha256', OG_SECRET).update(query).digest('hex');
  return `${OG_BASE}?${query}&sig=${sig}`;
}

Then in your page template, add the meta tags:

<meta property="og:title" content={title} />
<meta property="og:image" content={getOgImageUrl({ title, excerpt, slug })} />

That's it. The scraper fetches the image URL, your API renders and caches it, and every share of that page shows a custom card.

The Bottom Line

How to Translate Game Localization Files (.JSON / .PO) Without Breaking Code Variables

Hugo Bernardo Cardoso — Mon, 27 Jul 2026 18:38:44 +0000

Introduction: The Scale vs. Code Integrity Dilemma
Localizing an indie game or a software product is no longer optional. On platforms like Steam, offering the standard 28-language catalogue (including Simplified Chinese, Japanese, Korean, German, and Brazilian Portuguese) routinely unlocks over 50% of a game's total revenue potential.
Yet, indie game developers face a brutal trade-off:
Human Translation Agencies: Charging $\$0.10$ to $\$0.20$ per word. Localizing a modest 20,000-word game into 28 languages can easily cost $\$30,000+$, completely pricing out solo developers and small teams.
Traditional Enterprise SaaS (Lokalise, Crowdin): Charging $\$50$ to $\$200+$ per month just for workspace access, forcing developers into bloated workflows and complex account setups.
Naïve Single-Pass AI (Raw ChatGPT/Claude): Fast and cheap, but destructive to game builds.

This article explores the technical breakdown of why standard LLMs fail when processing code files, and details the engineering architecture required to build a code-safe, zero-friction localization pipeline.
Section 1: Anatomy of a Build Crash - Why Raw LLMs Corrupt Code
Large Language Models (LLMs) are statistical text predictors designed for natural human prose. They lack an internal compiler or Abstract Syntax Tree (AST) context when reading a raw file.
When you paste a .json, .po, .yaml, or .csv file into a standard LLM, five distinct failure modes occur:

Variable & Token Mutation Game engines rely on runtime string interpolation. When an LLM encounters: JSON "hud_gold": "You collected {gold_amount} coins from {monster_type}." It frequently translates the variable names inside the brackets: JSON "hud_gold": "Você coletou {quantidade_ouro} moedas de {tipo_monstro}." // ❌ CRASH: Engine looks for {gold_amount}
Positional & Printf Specifier Mangling C-style formatting specifiers like %s, %d, %f, or :user are often dropped, reordered without positional indexes, or spaced out: JSON "save_slot": "Save file %s loaded." -> "Save file % s loaded." // ❌ PARSE ERROR
ICU Plural Rule Destruction Complex game strings use ICU plural syntax to handle numerical agreement: Plaintext {count, plural, =0 {No items} =1 {One item} other {# items}} Standard LLMs frequently translate the structural control keywords (plural, other), breaking the engine's localization parser entirely.
Rich Text & HTML Tag Pollution Game engines (like Unity's TextMeshPro or Godot's RichTextLabel) use inline markup like or [b]. LLMs often translate color names (), drop closing tags, or convert angle brackets into unescaped HTML entities (<color>).
Unescaped Quotes and Structural Syntax Errors In JSON or YAML files, if a translated French or Spanish string contains an unescaped double quote (e.g., "desc": "L'épée de l' "héros" "), the resulting output becomes invalid JSON, breaking the entire game build at boot. Section 2: Architecture of an Engine-Aware Localization Engine To guarantee zero build breaks, the translation process must be decoupled from the raw file structure. The LLM must never be allowed to touch raw code variables. Here is the technical architecture behind LocaFile AI: Plaintext ┌────────────────┐ ┌───────────────────────┐ ┌───────────────────────┐ │ Source File │ ──> │ Engine Regex Parser │ ──> │ Token Masking │ │ (JSON/PO/CSV) │ │ Auto-Detect Format │ │ {var} ──> [[LOCK_0]] │ └────────────────┘ └───────────────────────┘ └───────────────────────┘ │ ┌────────────────┐ ┌───────────────────────┐ ▼ │ Delivered ZIP │ <── │ Post-Processing QA │ <── ┌───────────────────────┐ │ (28 Languages) │ │ AST Validation & Fix │ │ 3-Pass AI Engine │ └────────────────┘ └───────────────────────┘ │ + Lore & Tone Rules │ └───────────────────────┘ A. Engine Format Auto-Detection & AST Parsing The system supports 9 engine formats out of the box: Godot: .po, Godot .csv (multi-column Unity: Unity .csv, i18n .json Unreal & Mobile: XLIFF, iOS .strings, Android .xml Web Frameworks: .yaml, .tsv, Laravel PHP lang arrays

An AST parser extracts translatable values while maintaining the exact key mapping, structural nested hierarchy, and array index positions.
B. The Immutable Variable Locker
Before any prompt is constructed, a multi-stage Regex scanner identifies all control variables, HTML/rich-text tags, positional specifiers, and ICU blocks:
Detection: Identifies patterns matching {...}, %s, %d, :key, , [tag], and indexed placeholders {0}.
Replacement: Replaces each detected variable with an immutable, deterministic lock token: [[LOCK_0]], [[LOCK_1]], etc.
Why Double Square Brackets? Double square bracket tokens ([[LOCK_N]]) do not naturally occur in legitimate game dialogue or software strings. They prevent LLM tokenization distortion and survive the AI translation pass untouched.

C. Lore Glossaries & Prompt Injection Protection
Game lore uses proper nouns (character names, fictional planets, unique spells) that must remain identical across all languages.
Lore Glossary Engine: Developers can pass up to 2,000 characters of proper nouns (e.g., "CyberCore, Eldoria, X-400").
Security: Glossaries are validated against strict prompt-injection detection patterns before being appended as immutable system constraints.

D. Context & Tone Customization
Language register heavily impacts player immersion. A medieval RPG demands formal or archaic phrasing, while a modern shooter requires punchy, casual dialogue.
Developers can specify target registers:
Standard: Clean, neutral UI phrasing.
Casual: Natural, conversational registers (e.g., informal "tu" in French/Spanish).
Fantasy / Heroic: Immersive register for RPGs and story-driven titles.
Sci-Fi / Cyberpunk: Stylized technical phrasing.

Section 3: The Automated Post-Processing QA & Auto-Fix Pipeline
Even with prompt constraints, an production-grade system cannot rely solely on the LLM's output. A dedicated post-processing engine must validate every single key before packaging.

Linguistic Variable Checker (Regex AST Validator)

Before delivering the final ZIP bundle, a dedicated post-processing engine compares the source string against the target translation across 5 variable patterns:

Curly Brackets: {player_name}

Colon Specifiers: :attribute

Printf Tokens: %s, %d

Markup Tags: ,

Indexed Tokens: {0}, {1}

Defect Detection & Auto-Fix Engine

The QA validator flags three types of issues:

Missing Variables: The source string had {count}, but the translation dropped it.

Corrupted Variables: The AI altered the internal token (e.g., [[LOCK_0]] became [[LOCK_0_ES]]).

Extra Variables: Unsanitized tokens present in translation but absent in source.

Automated Re-Injection: When a missing variable is detected, the engine calculates its semantic position relative to surrounding words and automatically re-injects the missing {variable} into the translated string before generating a detailed report (quality-report.json).
Section 4: Pay-Per-Pass vs. Monthly Subscriptions
The SaaS industry is saturated with recurring monthly subscriptions that penalize developers during idle development phases. Indie game development is inherently bursty: you might localize heavily during a major launch or playtest, and then go months without needing translation updates.
Why Pay-Per-Pass Wins for Indie Game Devs:
PRICING COMPARISON:
Human Agencies : $0.10 - $0.20/word | High Cost | Manual Variable Handling
Enterprise SaaS : $50 - $200+/month | Subscription| Complex Workspace Setup
LocaFile AI : From $19 (Flat) | Pay-per-Pass| Automated Variable Protection
Indie Starter ($19): 3 runs, up to 5,000 words/file across 6 core languages (EFIGS + CJK).
Steam Launchpad ($99): 10 runs, up to 25,000 words/file across all 28 Steam catalogue languages.
Studio Pass ($249): 35 runs, up to 100,000 words/file for large-scale RPGs and studio pipelines.

Section 5: Hands-On Tutorial - Localizing a Game in 3 Steps
Step 1: Prepare Your Game File
Ensure your string keys are separated from translatable values in a supported format:
JSON
{
"quest_header": "Quest: Defeat {boss_name}",
"item_reward": "You earned {amount} gold coins!",
"dialogue_intro": "Welcome to Eldoria, traveler."
}
Step 2: Test Variable Protection (Zero-Cost Live Preview)
Navigate to locafileai.com and use the zero-cost Variable Protection Preview tool on the homepage.
Paste your raw JSON snippet to observe the production VariableLocker instantly convert {boss_name} and into protected [[LOCK_N]] tokens in real-time before initiating any pass.
JSON
// Real-time Variable Masking Output:
{
"quest_header": "Quest: Defeat [[LOCK_0]]",
"item_reward": "You earned [[LOCK_1]][[LOCK_2]][[LOCK_3]] gold coins!",
"dialogue_intro": "Welcome to Eldoria, traveler."
}
Step 3: Run the Pass & Import to Engine
Drop File or ZIP Batch: Drag your .json, .po, or .csv files directly onto the dropzone.
Set Glossaries & Tone: Add proper nouns to your Lore Glossary and select your game's tone (e.g., Fantasy or Casual).
Execute Pass: Select your target languages (or full 28 Steam catalogue) and watch live real-time WebSocket progress via Laravel Reverb.
Export & Build: Download your validated ZIP bundle and drop it directly into your Godot res:// or Unity Assets/Resources/ directories. Zero syntax errors, zero build breaks.

Conclusion
Game localization should not require thousands of dollars in agency fees or hours spent debugging broken JSON brackets and mangled variable names. By isolating variables through pre-parsing AST Regex lockers, applying post-processing QA validation, and offering a fair pay-per-pass pricing model, developers can expand their games to a global Steam audience with total code safety.
Test the real-time variable protection preview today at locafileai.com!

How to Localize a Godot Game Without Breaking Variable Tags

Hugo Bernardo Cardoso — Mon, 27 Jul 2026 18:36:12 +0000

How to Localize a Godot Game Without Breaking Variable Tags

Godot's localization system is built around a simple idea: separate your text from your code, translate the text, and let the engine swap it at runtime. In practice, the variable tags inside those strings are where things fall apart.

How Godot handles translatable strings

Godot, a free, open-source game engine used by solo developers and small studios for 2D and 3D projects, stores translatable text in CSV files or .po (gettext) files. You define a key, write your source string, and add columns or entries for each target language.

A typical CSV row might look like this:

QUEST_COMPLETE,"{player_name} finished the quest in {time} seconds"

And in GDScript, you call it with:

label.text = tr("{player_name} finished the quest in {time} seconds").format({
    player_name = player.name,
    weapon = str(elapsed)
})

Godot also supports C-style format strings (%s, %d) and rich text tags like [color=red] in its RichTextLabel nodes. These are all over a typical game's translation file, and they all need to survive translation intact.

Where translations break

The problem is not the translation itself. It is the variable tags inside the strings.

When you paste {player_name} picked up the {weapon} into a translation tool or general-purpose AI, several things can go wrong:

Curly braces get translated. Some tools interpret {player_name} as natural language and translate "player" and "name" into the target language. Your code calls .format() with the English key. It finds no match. The placeholder renders as raw text, or your game crashes.
Format specifiers get reordered. %s killed %d enemies depends on argument order. A translator might flip the sentence structure for grammar but leave %s and %d in the original positions, swapping which value fills which slot.
Rich text tags get mangled. [color=red]Warning[/color] might become [couleur=rouge]Avertissement[/couleur] in French output, breaking BBCode parsing entirely.
Whitespace around tags disappears. Tokenizers strip or merge spaces near braces and brackets, producing {player_name}picked up with no space between the variable and the next word.

These bugs are silent. The CSV file looks fine. The game launches. Then a Japanese player sees {player_name} rendered as literal text on screen because the translator converted the curly braces to full-width characters.

How to protect your tags

The reliable approach is to replace every variable tag with a placeholder token before translation, then restore the originals after.

Here is the process:

Scan each string for variable patterns. Match {...}, %s, %d, %f, [color=...]...[/color], and any custom tags your project uses.
Replace each match with a numbered token like __VAR_0__, __VAR_1__. Store the mapping.
Send only the tokenized string to translation. The translator (human or AI) sees plain text with inert tokens it has no reason to modify.
After translation, swap the tokens back to the original variable tags, byte for byte.

This is the approach LocaFile AI uses. When you upload a Godot CSV or .po file, it detects and locks every variable pattern, including {player_name}, %s, %d, and <color=red> tags, with regex-based token replacement before the AI model sees the string. After translation, the original tags are restored exactly. The AI only ever processes plain text with inert placeholders.

Practical checks before you ship

Even with tags protected, verify your translations before release:

Test with pseudolocalization. Godot has a built-in pseudolocalization mode (Project Settings > Internationalization > Locale) that replaces your strings with accented, elongated versions. It catches hardcoded strings you forgot to externalize and UI elements that overflow with longer text.
Check font coverage. Godot's default font only covers Latin-1 characters. For CJK, Cyrillic, Arabic, or Thai, load a font like Noto Sans as a DynamicFont resource and set it as your theme's default.
Handle pluralization properly. English has two plural forms. Polish has four. Arabic has six. Godot's tr_n() function handles this per-locale, but your source strings need to be structured for it: tr_n("There is %d apple", "There are %d apples", count).
Test RTL languages. If you are shipping in Arabic or Hebrew, Godot automatically mirrors UI anchors, margins, and control order. But icons with directional arrows (back/forward buttons) need manual attention.

The real cost of skipping localization

Steam's audience is global. Roughly 60% of Steam users have their client set to a non-English language. Shipping English-only means your store page, your reviews, and your in-game text are invisible to most of the platform.

The traditional path, hiring an agency, costs thousands of dollars per language and takes weeks. The shortcut of running your CSV through ChatGPT produces translations that look correct until {player_name} shows up as literal text on a player's screen.

Variable-safe translation closes that gap. Protect the tags, translate the text, verify with pseudolocalization, ship.