DEV Community: Daniel Schreiber

Affiliate opportunity for dev creators (B2B): Help teams ship i18n, earn 25% lifetime

Daniel Schreiber — Fri, 15 Aug 2025 09:28:52 +0000

Hey DEV folks 👋

We run doloc, a developer-first localization tool that plugs into your existing build. If your audience is devs/solo-founders/app builders, our affiliate program might be a great fit.

Why devs like doloc

Stays in the toolchain: run translations as a single curl/API step after extraction (no heavy platform).
Consistent style: uses your existing translations as an implicit glossary so new strings match prior wording.
Works nicely with Angular, FormatJS/React-Intl, Android, Flutter! Also a JetBrains IDEs plugin is available.

If you want examples for your content:
• Angular guide (how to wire extraction + doloc)
• FormatJS/React-Intl guide
• Flutter guide
These make solid tutorial posts/videos.

Affiliate terms

25% lifetime recurring commission
90-day cookie
Regular PayPal payouts
We’ll share logos, sample copy, and are happy to co-write a tutorial. Apply here: doloc.io/affiliate.

Content ideas you can riff on

“Shift Left: i18n in sync with development”
“CI-friendly i18n: translations as part of your pipeline”
“From one locale to five in an afternoon”
“Keeping translation style consistent without a manual glossary”

If this fits your audience, we’d love to partner. Questions welcome — happy to share demo projects and code snippets.

Disclosure: This is an affiliate recruitment post for our own product.

[Boost]

Daniel Schreiber — Sun, 02 Mar 2025 10:39:25 +0000

Deep Dive: xml-trueformat – Preserve XML Formatting with Ease

Daniel Schreiber ・ Mar 1

#xml #typescript

Deep Dive: xml-trueformat – Preserve XML Formatting with Ease

Daniel Schreiber — Sat, 01 Mar 2025 18:39:58 +0000

xml-trueformat is a TypeScript library for parsing and manipulating XML documents while retaining their exact original formatting. It stores whitespace, line breaks, comment placement, and attribute order—ensuring a no-op parse/serialize if you don’t change anything, and only minimal diffs when you do.

Why Formatting Preservation Matters

Many XML tools strip “insignificant” whitespace or reformat tags. For files where human-friendly layout and indentation matter—like configuration files, manifests, or annotated XML templates—this can be disruptive. xml-trueformat preserves every nuance of an XML file, so you can add elements or attributes programmatically without rewriting everything else.

When to (not) Use

Clearly, xml-trueformat satisfies a specific set of requirements - the following outlines, in which situations it fits well and where you should rather go for another parser.

Use xml-trueformat if:

You require exact round-trip output, preserving whitespace, comments, and attribute ordering.
You handle configuration or manifest files under version control where small diffs are critical.
You need to insert or remove nodes while leaving everything else unaltered.

Not ideal if:

You only need to parse XML data (no need for original layout) or convert to JSON.
You want fast, large-scale data extraction from huge XML files (performance overhead is higher here).
You prefer a simpler JSON-like object structure, e.g., from xml2js, and don’t care about formatting.

Quick Comparison with Other XML Parsers

xml2js: Converts XML to a JavaScript object, loses formatting and comments. Simpler for data but no layout fidelity.
fast-xml-parser: High performance, optional “preserveOrder” for node sequence, but still not guaranteed exact whitespace or comments in original positions.
DOM-based parsers (xmldom, etc.): May preserve some whitespace, but typically not attribute quotes/order or small spacing nuances. Re-serialization often changes formatting.
sax-js: An event-based streaming parser that’s great for processing large XML on-the-fly. It doesn’t build a modifiable DOM nor preserve formatting. Ideal for fast reads, not for round-trip exactness.

xml-trueformat is purpose-built for retaining everything. In exchange, it’s less streamlined for pure data transformations and may be slower for large files compared to specialized parsers.

How It Works

Under the hood, xml-trueformat uses its own AST (abstract syntax tree) rather than a standard DOM. Every piece of whitespace (indentation, newlines, spacing around attributes) is modeled as text nodes, plus specialized classes for comments, CDATA, etc. When you add or remove something, it automatically:

Matches Indentation of sibling nodes if possible.
Preserves Quoting Style from existing attributes (e.g., ' ' or " ").
Keeps Comments and Processing Instructions precisely where they were.
Distinguishes between self-closing and non-self-closing elements (e.g. <tag/> vs. <tag></tag>)

Smart Formatting on Modifications

The real magic of xml-trueformat is that when you insert new elements or attributes, it doesn't just plop them in arbitrarily – it matches the existing formatting style. Two helper methods illustrate this well: adding a new element and adding a new attribute (we'll only show the first here).

Inserting Elements without Breaking Indentation

Let’s say you have an XML list of entries:

<users>
    <user name="Alice"/>
    <user name="Bob"/>
</users>

If you want to add a new <user> element programmatically, you’d want it indented with the same 4 spaces as the others, and on its own new line. With xml-trueformat, you can do something like:

const newUser = new XmlElement('user', [new XmlAttribute('name','Charlie')]); 
userElement.addElement(newUser);

If there are sibling elements, xml-trueformat checks their whitespace usage (like line breaks and indentation) and applies the same to <user>. This results in a well formatted result:

<users>
    <user name="Alice"/>
    <user name="Bob"/>
    <user name="Charlie"/>
</users>

Of course you could as well manually control formatting, by using XmlElement.addChild which does not perform any "smart" formatting and gives you full control.

Example Workflow

import { XmlParser } from 'xml-trueformat'; 
import * as fs from 'fs';

const xmlData = fs.readFileSync('example.xml','utf8'); 
const doc = XmlParser.parse(xmlData);

// Modify attributes 
doc.getRootElement().setAttributeValue('version', '2.0');

// Add new element 
const newElem = new XmlElement('feature', [new XmlAttribute('enabled','true')]);
doc.getRootElement().addElement(newElem);

// Serialize 
fs.writeFileSync('output.xml', doc.toString());

The output remains faithful to the original indentation and spacing, with only the changes you requested.

Other Perks and Features

Comments and CDATA preserved: Comments, processing instructions, and CDATA sections are not lost or reformatted. They are part of the object model (e.g., there are XmlComment and XmlCData node types) and will round-trip through parse and serialize intact, at their original places.
No heavy dependencies: xml-trueformat is implemented in plain TypeScript with no external libraries required. This makes it lightweight and ensures compatibility in Node.js and in browsers. You can use it in a backend script or on a frontend page – anywhere you need to manipulate XML reliably.
Minimal footprint of change: When you do make modifications, xml-trueformat keeps the scope of changes minimal. If you diff the before vs after XML files, you’ll typically see only the lines related to your actual change. This makes code reviews and merges smoother.

Conclusion

xml-trueformat is an excellent choice for high-fidelity XML editing, especially where minor layout changes would be problematic. It’s not the fastest or simplest for data extraction, but if you want minimal diffs and lossless round trips, it’s hard to beat.

Questions or Feedback?

Let me know what features or improvements you’d like. Feel free to open an issue or PR on GitHub — feedback is always welcome!

Define, Generate, and Implement: An API-First Approach with OpenAPI Generator and FlightPHP

Daniel Schreiber — Mon, 24 Feb 2025 10:34:26 +0000

Adopting an API-first strategy ensures that your server and client remain in sync, dramatically reducing integration issues. By defining your API contract upfront, you can automatically generate both server stubs and client SDKs. This not only minimizes manual work but also creates a "typesafe" bridge between your front-end and back-end -- something even PHP developers can appreciate ;-)

Defining Your API

Begin by describing your API in an OpenAPI specification (e.g., my_api.yaml). In your spec, define endpoints, request/response schemas, and authentication details. For instance, a simple user endpoint might be defined as follows:

openapi: 3.0.0
info:
  title: Example API
  version: 1.0.0
paths:
  /users/{id}:
    get:
      summary: Retrieve a user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: A user object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
    put:
      summary: Update a user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '204':
          description: User updated
components:
  schemas:
    UserState:
      type: string
      enum:
        - active
        - disabled
        - pending
    User:
      type: object
      required:
        - id
        - state
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
        state:
          $ref: '#/components/schemas/UserState'

While this might seem bloated at first glance, bear with me — this approach makes subsequent implementations much easier and more robust!

Generating the Server Stub and Client SDK

With your API defined, use the OpenAPI Generator to generate your code automatically. The PHP Flight generator — documented here — was provided by the author and, although its status is still marked as "experimental", it has been my production workhorse for over a year.

Here’s an example shell script that automates the generation of a FlightPHP server stub:

#!/bin/bash
set -e

OPEN_API_GEN_VERSION="7.9.0"
GENERATOR_JAR="openapi-generator-cli-${OPEN_API_GEN_VERSION}.jar"

# Download the generator if needed:
if [ ! -f "$GENERATOR_JAR" ]; then
    curl -o "$GENERATOR_JAR" "https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/${OPEN_API_GEN_VERSION}/openapi-generator-cli-${OPEN_API_GEN_VERSION}.jar"
fi

# Clean previous outputs
rm -rf generated-server

# Generate a FlightPHP server stub using the php-flight generator
java -jar "$GENERATOR_JAR" generate -i my_api.yaml -g php-flight -o generated-server --additional-properties=invokerPackage=GeneratedApi,composerPackageName=myapi/server

Of course, you can similarly generate your API (frontend) clients. This automated process ensures that any changes to your API spec are consistently propagated across all layers, keeping your integration robust and typesafe. You can choose whether to track these generated files in version control or simply re-generate them in your CI build.

Check Out the Generated Source

The generated files form a complete composer package, that you could package and use as dependency. Here we'll keep it in a subfolder and include it as a local composer repository. Assume you generated the following into a folder generated-server in you project:

├── Api
│   └── AbstractDefaultApi.php
├── Model
│   ├── User.php
│   └── UserState.php
├── README.md
├── RegisterRoutes.php
├── Test
│   └── RegisterRoutesTest.php
├── composer.json
└── phpunit.xml.dist

Then you can require this in your composer.json as follows:

{
  // other properties ...
  "repositories": [
    {
      "type": "path",
      "url": "generated-server/"
    }
  ],
  "require": {
    "myapi/server": "*",
    // other dependencies ...
  }
}

The User model, for example, looks like this (without comments for better readability):

<?php

namespace GeneratedApi\Model;

class User implements \JsonSerializable
{
    public int $id;
    public ?string $name;
    public ?string $email;
    public UserState $state;

    public function __construct(int $id, ?string $name, ?string $email, UserState $state)
    {
        $this->id = $id;
        $this->name = $name;
        $this->email = $email;
        $this->state = $state;
    }

    public static function fromArray(array $data): self
    {
        return new self(
            $data['id'] ?? null, 
            $data['name'] ?? null, 
            $data['email'] ?? null, 
            isset($data['state']) ? UserState::tryFrom($data['state']) : null, 
        );
    }

    public function jsonSerialize(): mixed {
        return [
            'id' => $this->id, 
            'name' => $this->name, 
            'email' => $this->email, 
            'state' => $this->state, 
        ];
    }
}

Implementing Your API Endpoints

Once your server stub is generated, extend the generated abstract API classes to implement your business logic. The generated API classes contain method stubs with correct parameter and return types for every path from your API specification. An example implementation for the User API might look like this:

<?php

namespace MyApp\Api;

use GeneratedApi\Api\AbstractDefaultApi;
use GeneratedApi\Model\User;
use GeneratedApi\Model\UserState;
use Flight;

class UserApi extends AbstractDefaultApi
{
    #[\Override]
    public function usersIdGet(int $id): ?User {
        // Simulate fetching a user from a data source
        if ($id === 1) {
            return new User(1, 'Alice Smith', 'alice@example.com', UserState::PENDING);
        }
        Flight::halt(404, "User not found");
        return null;
    }

    #[\Override] 
    public function usersIdPut(int $id, User $user): void {
         // store user in DB - might use $user->jsonSerialize() for serialization
    }
}

Note: You do not need to overwrite all methods! If you like to handle some routes manually, just ignore these method stubs (and manually register these routes with FlightPHP).

After implementing your API logic, register your endpoints with FlightPHP to integrate them into your application routing:

<?php

// In your Flight bootstrap file
use MyApp\Api\UserApi;
use GeneratedApi\RegisterRoutes;

RegisterRoutes::registerRoutes(new UserApi()); 
// this is the place you'd manually invoke `Flight::route()`

Flight::start();

This ties your custom implementation to FlightPHP’s routing system, ensuring that your API behaves as defined. The RegisterRoutes::registerRoutes() method is generated by the generator and automatically checks which methods were implemented in UserApi and registers them with Flight:route() for the correct paths. Also it de-/serializes request/response objects for you.

Note all the things you don't need to do with this approach:

No manual de-/serialization needed (you get your parameters in correct type - e.g. userId as int!)
No manual checking if response/request is as expected (conforms to schema)
No manual set up of paths/routes

Final Thoughts

By following an API-first approach with OpenAPI Generator and FlightPHP, you ensure a consistent, typesafe contract between your front-end and back-end. While the initial setup might take a little effort, it quickly pays off during subsequent iterations. This strategy treats your API as first-class citizen and helps you maintaining this API with any upcoming changes!

I’d love to hear your thoughts or experiences with this approach. Please share your feedback or any questions you might have.

Android XML Resources: Automated Translations with doloc

Daniel Schreiber — Sat, 25 Jan 2025 18:21:43 +0000

Developing multilingual apps efficiently can be a real challenge - especially when working with various frameworks and tools. This is where doloc comes into play: a lightweight solution for automated translations that integrates seamlessly into your existing workflows. The focus is on great translations and no need for a glossary, as all texts automatically serve implicitly as a glossary.

Today, we’re excited to introduce our latest integration for Android!

In this article, we’ll show you how to use doloc to automate translations in your Android project and save valuable time. It takes you only two steps before you can extract and translate your texts automatically!

Android: Automating Translations with doloc

Set up Andoroid Localization with the Andorid documentation.
Add doloc to your workflow by adding the following to your Gradle scripts. Use Groovy or Kotlin DSL depending on your project setup.

Groovy DSL (build.gradle):

import java.net.URI
import java.net.http.HttpClient
import java.net.http.HttpRequest
import java.net.http.HttpResponse
import java.nio.file.Files
import java.nio.file.Path

// other existing plugins/tasks..

static def translate(String targetLang, Path sourceFile, Path targetFile) {
  def boundary = "Boundary-${System.currentTimeMillis()}"
  HttpClient.newHttpClient().send(
    HttpRequest.newBuilder().uri(URI.create("https://api.doloc.io?targetLang=$targetLang"))
      .header("Content-Type", "multipart/form-data; boundary=$boundary")
      .header("Authorization", "Bearer ${System.getenv("API_TOKEN")}")
      .POST(
        HttpRequest.BodyPublishers.ofString(
          "--$boundary\r\n" +
          "Content-Disposition: form-data; name=\"source\"; filename=\"${sourceFile.fileName}\"\r\n" +
          "Content-Type: application/octet-stream\r\n\r\n" +
          "${Files.readString(sourceFile)}\r\n" +
          "--$boundary\r\n" +
          "Content-Disposition: form-data; name=\"target\"; filename=\"${targetFile.fileName}\"\r\n" +
          "Content-Type: application/octet-stream\r\n\r\n" +
          "${Files.readString(targetFile)}\r\n" +
          "--$boundary--\r\n"
        )
      )
      .build(), HttpResponse.BodyHandlers.ofFile(targetFile)
  )
}

tasks.register("doloc-fr") {
  doLast {
    translate(
      "fr",
      project.file("app/src/main/res/values/strings.xml").toPath(),
      project.file("app/src/main/res/values-fr/strings.xml").toPath()
    )
  }
}

tasks.register("doloc-es") {
  doLast {
    translate(
      "es",
      project.file("app/src/main/res/values/strings.xml").toPath(),
      project.file("app/src/main/res/values-es/strings.xml").toPath()
    )
  }
}

tasks.register("update-i18n") {
  dependsOn("doloc-fr", "doloc-es")
}

Kotlin DSL (build.gradle.kts):

import java.net.URI
import java.net.http.HttpClient
import java.net.http.HttpRequest
import java.net.http.HttpResponse
import java.nio.file.Files
import java.nio.file.Path

// other existing plugins/tasks..

fun translate(targetLang: String, sourceFile: Path, targetFile: Path) {
  val boundary = "Boundary-${System.currentTimeMillis()}"
  HttpClient.newHttpClient().send(
    HttpRequest.newBuilder().uri(URI.create("https://api.doloc.io?targetLang=$targetLang"))
      .header("Content-Type", "multipart/form-data; boundary=$boundary")
      .header("Authorization", "Bearer ${System.getenv("API_TOKEN")}")
      .POST(
        HttpRequest.BodyPublishers.ofString(
          "--$boundary\r\n" +
          "Content-Disposition: form-data; name=\"source\"; filename=\"${sourceFile.fileName}\"\r\n" +
          "Content-Type: application/octet-stream\r\n\r\n" +
          "${Files.readString(sourceFile)}\r\n" +
          "--$boundary\r\n" +
          "Content-Disposition: form-data; name=\"target\"; filename=\"${targetFile.fileName}\"\r\n" +
          "Content-Type: application/octet-stream\r\n\r\n" +
          "${Files.readString(targetFile)}\r\n" +
          "--$boundary--\r\n"
        )
      )
      .build(), HttpResponse.BodyHandlers.ofFile(targetFile)
  )
}

tasks.register("doloc-fr") {
  doLast {
    translate(
      "fr",
      project.file("app/src/main/res/values/strings.xml").toPath(),
      project.file("app/src/main/res/values-fr/strings.xml").toPath()
    )
  }
}

tasks.register("doloc-es") {
  doLast {
    translate(
      "es",
      project.file("app/src/main/res/values/strings.xml").toPath(),
      project.file("app/src/main/res/values-es/strings.xml").toPath()
    )
  }
}

tasks.register("update-i18n") {
  dependsOn("doloc-fr", "doloc-es")
}

Make sure to update the translation file paths and to replace ${System.getenv("API_TOKEN")} with your API token or set a corresponding environment variable.
The $API_TOKEN can be found in your doloc account.

Now run gradle update-i18n to translate all new texts into all target languages!

When should the skript be run by the developer?

This script should be run after adding or updating translations and not on the CI/CD pipeline. This has the advantage that the code always stays in sync with the translations and that the developer can check the translations before committing and/or merging them. (Furthermore, this simplifies the CI/CD pipeline and prevents unnecessary commits for translations only.)

How to handle updated texts?

When changing texts in the source file, one should remove the corresponding texts in the target file to ensure that the translations are updated. Alternatively, one can manually update the translations in the target file, of course.

More Info

To find more info and details to integrate doloc into your Andorid workflow follow our Guide: https://doloc.io/getting-started/frameworks/android/.

Also we provide detailed information on configuration of specific options in the URL in our Android XML Resources guide.

Summary

By using the Android integration of doloc you have the following advantages:

Easy integration into the development workflow
Instant translations of texts via API
Consistent style without a dictionary
Reduced translator workload
Accelerated time to market
And, of course: Great translations!

Leave a comment or send us a message in case you need help or you have questions!

P.S. This also works for many other formats and frameworks!
Be sure to check out our guides for Angular and FormatJS/react-intl.

Integration for FormatJS/react-intl: Automated Translations with doloc

Daniel Schreiber — Sat, 11 Jan 2025 18:59:51 +0000

Today, we’re excited to introduce our latest integration for FormatJS/react-intl!

In this article, we’ll show you how to use doloc to automate translations in your FormatJS/react-intl project and save valuable time. It takes you only two steps before you can extract and translate your texts automatically!

FormatJS/react-intl: Automating Translations with doloc

Set up react-intl with the offical FormatJS guide.
Add doloc to your workflow by adding the following to your package.json script:

{
  "scripts": {
    // other scripts ...
    "extract": "formatjs extract \"src/**/*.ts*\" --ignore=\"**/*.d.ts\" --out-file src/lang/en.json --id-interpolation-pattern '[sha512:contenthash:base64:6]'",
    "doloc-fr": "curl https://api.doloc.io -H \"Authorization: Bearer $API_TOKEN\" -F source=\"@src/lang/en.json\" -F target=\"@src/lang/fr.json\" -o src/lang/fr.json",
    "doloc-es": "curl https://api.doloc.io -H \"Authorization: Bearer $API_TOKEN\" -F source=\"@src/lang/es.json\" -F target=\"@src/lang/es.json\" -o src/lang/es.json",
    "format-js-compile-en": "formatjs compile src/lang/en.json --ast --out-file src/compiled-lang/en.json",
    "format-js-compile-fr": "formatjs compile src/lang/fr.json --ast --out-file src/compiled-lang/fr.json",
    "format-js-compile-es": "formatjs compile src/lang/es.json --ast --out-file src/compiled-lang/es.json",
    "update-i18n": "npm run extract && npm run doloc-fr && npm run doloc-es && npm run format-js-compile-en && npm run format-js-compile-fr && npm run format-js-compile-es"
  }
}

The $API_TOKEN can be found in your doloc account.

Now run npm run update-i18n to extract new translations and automatically translate them.

To find more infos and details for configuration follow our guide on https://doloc.io/getting-started/frameworks/react-intl-format-js/.
There you'll also find information on how to handle explicit IDs.

Summary

By using the FormatJS/react-intl integration of doloc you have the following advantages:

Easy integration into the development workflow
Instant translations of texts via API
Consistent style without a dictionary
Reduced translator workload
Accelerated time to market
And, of course: Great translations!

Leave a comment or send us a message in case you need help or you have questions!

P.S. This also works for many other formats and frameworks!
Be sure to check out our guides for Android and Angular.

Integration for Angular: Automated Translations with doloc

Daniel Schreiber — Sat, 11 Jan 2025 18:59:36 +0000

Today, we’re excited to introduce our latest integration for Angular!

In this article, we’ll show you how to use doloc to automate translations in your Angular project and save valuable time. It takes you only three steps before you can extract and translate your texts automatically!

Angular: Automating Translations with doloc

Set up Angular Localization i18n with the official Angular guide.
Set up ng-extract-i18n-merge to manage translations.
Add doloc to your workflow by adding the following to your package.json script:

{
  "scripts": {
    // other scripts ...
    "auto-translate-fr": "curl https://api.doloc.io -H \"Authorization: Bearer $API_TOKEN\" --data-binary @src/messages.fr.xlf -o src/messages.fr.xlf",
    "auto-translate-it": "curl https://api.doloc.io -H \"Authorization: Bearer $API_TOKEN\" --data-binary @src/messages.it.xlf -o src/messages.it.xlf",
    "update-i18n": "ng extract-i18n && npm run auto-translate-fr && npm run auto-translate-it"
  }
}

The $API_TOKEN can be found in your doloc account.

Now run npm run update-i18n to extract new translations and automatically translate them.

To find more info and details for configuration follow our guide on https://doloc.io/getting-started/frameworks/angular/.

Summary

By using the Angular integration of doloc you have the following advantages:

Easy integration into the development workflow
Instant translations of texts via API
Consistent style without a dictionary
Reduced translator workload
Accelerated time to market
And, of course: Great translations!

Leave a comment or send us a message in case you need help or you have questions!

P.S. This also works for many other formats and frameworks!
Be sure to check out our guides for Android and FormatJS/react-intl.

App Localization with doloc

Daniel Schreiber — Mon, 11 Nov 2024 21:27:35 +0000

In this post, I'll outline an optimized translation workflow for app localization¹. This approach applies to both web and native applications (iOS, Android, Windows, etc.), with just one prerequisite: using XLIFF (1.2 or 2.0) for your translation files. XLIFF is widely supported across localization tools, making it a practical choice for most teams.

The proposed setup can dramatically reduce time-to-market and lower translation costs.

The Traditional Workflow

To understand where bottlenecks and delays arise, let’s take a quick look at the traditional localization workflow:

Typically, translations are handled by third parties rather than developers themselves. This might be an agency, an in-house service, or another individual we’ll refer to as the "translator."

Extraction: The developer extracts the app's text into translation files (XLIFF).
Handover: The extracted files are handed over to the translator, usually in batches. This batching contributes significantly to delays; for example, new texts may only be sent for translation every two weeks.
Translation: The translator works on these files, translating new or updated text and striving to maintain language consistency. This step, often taking 1-3 days, requires effort and is prone to errors, particularly in larger apps with limited tooling support.
Integration: Once translations are complete, the files are handed back to the developer to integrate into the codebase. With the delay, this can involve resolving complex conflicts, adding manual effort to the process.

In summary:

Localization Delays: Typically, there’s a period of two weeks or more where the app isn’t fully localized, which can block releases or degrade the user experience for non-default languages.
Manual and Error-Prone Steps: The manual handover and integration steps increase costs and the likelihood of errors.

A Leaner Workflow with Automated Translations

By integrating doloc into the extraction process, you can streamline this workflow significantly. Here’s how it works:

Instead of a separate translation step, the extracted XLIFF files are sent to doloc automatically (via a simple curl command - see getting started. Doloc immediately translates the content and returns the updated files. The entire process boils down to just one step (plus an optional QA step):

Extraction and Translation: The developer extracts the text into XLIFF files, and doloc instantly translates them. The files are updated right away, so translations are available from the start.
Optional: Quality Assurance (QA): If desired, a translator can quickly validate automated translations. XLIFF includes specific states (e.g., "translated," "final") to mark reviewed segments.

This automated setup means QA efforts are minimal, and releases are no longer delayed by translation. Since your app is always localized, you may even find yourself reducing QA cycles as you gain confidence in the quality of doloc’s translations.

Additional Benefits:

Continuous Localization: Translations are always up to date, ensuring a fully localized experience for users across languages.
Integrated Testing: Localized text can be included in your acceptance tests, helping you catch potential issues early and maintain overall quality.

We Value Your Feedback

Disclaimer: I am the founder of doloc.

We're always working to improve. If you've tried doloc (we offer a free 14-day trial!) or if you have thoughts on whether it might fit into your workflow, we’d love to hear from you. Drop a comment below!

Localization includes more than just translation, but since other aspects are often centrally controlled or configured, we focus here on translation as the primary challenge. ↩

Client side (temporary) IDs

Daniel Schreiber — Thu, 21 Apr 2022 15:34:25 +0000

Why

Modern UIs often implement offline capabilities and/or follow the optimistic ui pattern. In these cases you'd need to handle new entities in your client side state before a server response (which traditionally contains the ID) is available. To support this, it is helpful to create IDs on the client side.

When you create IDs client side, you could follow different setups:

Traditional Server Server does not know about any client side IDs. Client "merges" server generated IDs.
Client only Server does not generate IDs but expects (all) clients to provide IDs. Normally used with UUIDs.
Server side mapping Clients propagate their generated ID to the server, but the server generates new ID and keeps/creates (a mapping of) both IDs (e.g. adding an attribute client_id to the entity).

Even though all setups are sensible (depending on the specific context), I'd like to highlight that only "Traditional Server" can be used for scenarios where you have no control over the server/API (or do not want to change these).

The following sections will focus on the Traditional Server setup and document some best practices. Please reach out if something seems incorrect or missing!

Keep temporary ID around

Even after the server supplied the (persistent) ID, it is often helpful to keep the corresponding temporary ID around - at least until the entity is removed from the client state.

For example this is useful when tracking list/table entries (e.g. with a trackBy function in Angular):

trackBy = (item, index) => item.temporaryId ?? item.id;

The above can only continuously identify the object, if you do not remove the temporaryId (even once the id is present).

Note: If you use the temporary ID in your URL, you should replace the URL with the persistent ID as soon as possible to make sure on a page refresh (when client state is generally reset) it is possible to re-fetch the entity from the server.

Use a separate attribute

You can put the client generated ID into the same attribute as the server generated ID. In this case it is advisable to clearly distinguish client/local IDs and server IDs - e.g. by prefix or by using negative numbers.

Generally it is easier to maintain your code if the client/local ID is put into a separate attribute - e.g. temporaryId. Not only does this enable to "Keep temporary ID around" (see above), but it is also less error prone, as you cannot mistakenly mix up client and server IDs.

In Typescript you can easily define an interface

interface HasTempId {
  temporaryId?: string;
}

and join this into your models:

const entity: YourEntity & HasTempId = {/* whatever */};

This makes it easy, to retrospectively add client side generated IDs to already existing code.

Admittingly, this is not as easy for nominally typed languages such as Java.

Referential Consistency

When entities reference other entities, these references should be taken into account. In general it is not necessary to create additional properties to hold temporary references, but you can first put the temporary/client ID into the original reference attribute and replace it with the persistent ID, once it is available. Of course, you should take care that all references of all relevant entities are updated.

This works naturally with central state patterns, such as Redux.

Stable order

If you have sub-resources modeled as a list that have IDs on their own (UML "Aggregation") you need to match all elements. To correctly associate client side IDs with server side IDs, the easiest way is to guarantee the order of this list (server) and just associate elements by their index.

In case the former is not possible you can still identify elements by their structure/values. Note that if you cannot distinguish elements, the correct order does not matter.

Conclusion

Generating and maintaining client side temporary IDs does add some complexity. A structured approach and using a modern (Web) stack with Typescript and a centralized state management helps keeping the solution maintainable.

Angular i18n update workflow

Daniel Schreiber — Thu, 20 Jan 2022 14:21:59 +0000

Problem

Reading this, you are probably already aware, that tooling for updating internationalization files in angular is limited (non-existent). You can easily extract translation texts from your templates with the ng extract-i18n command - but it is not clear, how to merge new/removed/changed texts into already translated language files.

The core team does not see it as their responsibility - see angular/angular/issues/37655 and angular/angular-cli/issues/6552. There existed some tooling @ngx-i18nsupport on which the community relied, but sadly this is unmaintained and broken (and probably too complex for "fork and repair"...).

Solution

Update

As the below solution is a little cumbersome, I created a plugin that nicely integrates with Angular CLI: https://github.com/daniel-sc/ng-extract-i18n-merge
With that setup comes down to

ng add ng-extract-i18n-merge

and extraction and merging gets as simple as

ng run [PROJECT_ID]:extract-i18n-merge

or (if you confirmed to adding an npm command):

npm run extract-i18n-merge

I wrote two small tools, that solve the i18n merge problem: xliff-simple-merge and xml_normalize.

The following example setup illustrates how you can extract, merge and normalize (remove "notes", sort by ID, pretty print) translations for your angular app with a single command:

npm run i18n-extract

Setup to be included in "scripts" of package.json (assuming you use XLIFF 2.0 format):

{
  ...
  "scripts": {
    ...
    "i18n-extract": "ng extract-i18n --format xlf2 --output-path src/i18n && npm run normalize-xliff-base && npm run merge-xliff-all && npm run normalize-xliff-all",
    "merge-xliff-all": "npm run merge-xliff-de && npm run merge-xliff-fr",
    "merge-xliff-de": "node node_modules/xliff-simple-merge -i src/i18n/messages.xlf -d src/i18n/messages.de.xlf",
    "merge-xliff-fr": "node node_modules/xliff-simple-merge -i src/i18n/messages.xlf -d src/i18n/messages.fr.xlf",
    "normalize-xliff-all": "npm run normalize-xliff-base && npm run normalize-xliff-de && npm run normalize-xliff-fr",
    "normalize-xliff-base": "node node_modules/xml_normalize -n -i src/i18n/messages.xlf -o src/i18n/messages.xlf -r /xliff/file/unit/notes -s /xliff/file/unit/@id",
    "normalize-xliff-de": "node node_modules/xml_normalize -n -i src/i18n/messages.de.xlf -o src/i18n/messages.de.xlf -r /xliff/file/unit/notes -s /xliff/file/unit/@id",
    "normalize-xliff-fr": "node node_modules/xml_normalize -n -i src/i18n/messages.fr.xlf -o src/i18n/messages.fr.xlf -r /xliff/file/unit/notes -s /xliff/file/unit/@id",
  },
  "devDependencies": {
    ...
    "xliff-simple-merge": "0.4.0",
    "xml_normalize": "0.8.1"
  }
}

Other work

If you (as the developer) do the translations yourself, you might find a more integrated solution, like angular-t9n, better.

Feedback welcome!

If you have a better setup or suggestions for improvement I'd be happy, if you leave a comment :-)

Testing STOMP websocket with Postman

Daniel Schreiber — Thu, 12 Aug 2021 12:23:21 +0000

With Postman v8 you can test Websockets - great! But..

When testing STOMP servers you will encounter a problem:

The body is then followed by the NULL octet.

See https://stomp.github.io/stomp-specification-1.2.html#STOMP_Frames

The only way (on windows) to get the NULL octet into the frame is by using the "binary/Base64" encoding (see screenshot below).

To easily convert the frame you can use Notepad++:

Activate "Character Panel"
Add "NULL" at the end of the frame (after all headers and body) - make sure to actually click on "NULL"
Select complete frame and encode it to Base64

If you found an easier way, please comment!

Firebase function retries with pubsub

Daniel Schreiber — Thu, 11 Feb 2021 09:10:30 +0000

Ever tried to use exponential backoff for pubsub triggered firebase functions? It’s not straight forward, but I’ll walk you through.

Why?

Decoupling cloud/firebase functions from the trigger/invocation via pubsub message topics is a best practice to improve reliability and resilience. Especially for the latter you’d want to have a sensible retry setup, so that transient errors are retried. This retry can be configured in the pubsub subscription that triggers the function.

What is the problem?

Consider this function:

export const myFunction = functions.region('europe-west1')
    .runWith({failurePolicy: {retry: {}}})
    .pubsub.topic('my-topic')
    .onPublish(...)

When deploying the function using the firebase cli, the subscription is recreated with standard retry settings. Using the firebase cli, it is currently not possible to define exponential backoff for the retry.

Note that the default settings can have a severe impact on your cloud bill. When retries are enabled (failurePolicy: {retry: {}}), the standard configuration retries immediately and for 7 days! So for non-transient errors or problems with a longer recovery time, you’ll pay for many invitations..

What is the solution?

After each function deployment, you need to update the subscription accordingly. The following configures retries with exponential backoff for at most 2 hours and delays between 10 seconds and 10 minutes:

# regular deployment:
firebase deploy --only functions --force
# update pubsub subscription for retries with exponential backoff:
gcloud pubsub subscriptions update \
 projects/$GCP_PROJECT_ID/subscriptions/gcf-myFunction-europe-west1-my-topic \
 --min-retry-delay=10s \
 --max-retry-delay=10m \
 --message-retention-duration=2h

Note that --force is needed in CI setup to deploy functions with retries.

What are the alternatives?

You could as well

manually update the subscription (not recommend)
move from firebase cli to a direct deployment on GCP (eg via terraform)

If I missed something or you have other solutions, please comment!