DEV Community: hans

Localizing a Shopify Customer Account Extension: 42 Languages, One Rails Server, and a Cache That Never Hit

hans — Fri, 12 Jun 2026 12:16:13 +0000

A customer in São Paulo opens their order status page. Shopify renders the whole page in Portuguese — and then our order editing widget shows up in the middle of it speaking English.

Worse: the merchant can't fix it. The copy is baked into the extension bundle at deploy time. "Cancel order" reads the same for a boutique in Berlin and a streetwear brand in Tokyo, in a language most of their customers don't shop in.

This is the story of how I built localization for PostCo's Order Editing app end-to-end — and the two edge cases that taught me more than the happy path did.

Context

PostCo Order Editing is a Shopify app that lets customers edit their own orders after checkout — add products, cancel the order, change the shipping address, switch payment methods — directly from the order status page. The customer-facing part is a Shopify customer account UI extension running in a sandboxed iframe; the backend and merchant admin are Rails 8 with Inertia and React.

Shopify UI extensions have built-in i18n: you bundle static JSON locale files and call shopify.i18n.translate(key). We shipped with English and French that way. It works, but the files are baked in at build time and identical for every shop:

Locale files are compiled into the extension bundle at deploy time.
Every shop receives the exact same strings.
Adding a language means a new release of the extension.
Merchants have no way to touch any of the copy.

The Problem

Two requirements converged.

Coverage. Merchants sell globally and Shopify localizes everything around our extension. We needed the extension to render in the customer's language — for the full set of locales Shopify supports, not two.

Customization. Merchants wanted to change the copy. Tone of voice, legal phrasing, a CTA that matches their theme. Bundled JSON gives them nothing — every shop gets identical strings.

Bundled locale files solve neither. Any solution had to put the copy somewhere our server controls, per shop, per language.

The Solution

A new server-owned translation system that:

Makes Rails own the catalog — one YAML file per locale under config/order_editing_locales/, 42 locales, 378 keys each, with en.yml as the source of truth.
Stores merchant overrides as sparse rows in a shop_translations table. Defaults are never copied into the database.
Adds a Localization page in the admin where merchants edit any string in any language, plus the existing Customize tab writing to the same rows.
Has the extension fetch resolved translations from Rails at runtime — GET /shopify_api/translations?locale=fr — falling back to its bundled copy if the request fails.
Layers three small caches to make the runtime fetch cheap, because two Shopify platform constraints kill the standard playbook (more on this below).

The deliberate trade: we chose server-delivered translations over publishing to Shopify metafields. Metafields would give zero-network reads, but every merchant edit would need a background publish job, every new key a backfill across all shops, and the admin "save and preview" flow would inherit eventual-consistency bugs. Serving from Rails means one source of truth and instantly visible edits — at the cost of a network request we then have to make cheap.

Implementation

The catalog and locale resolution

YAML is nested for maintainability, but the extension consumes flat dotted keys (matching what shopify.i18n.translate already used), so the loader flattens on read:

def flatten(value, prefix = nil)
  case value
  when Hash
    value.each_with_object({}) do |(key, child), translations|
      flattened_key = [prefix, key].compact.join(".")
      translations.merge!(flatten(child, flattened_key))
    end
  else
    { prefix => value.to_s }
  end
end

The loader also owns locale resolution, because what browsers report and what catalogs exist are different vocabularies:

LOCALE_ALIASES = { "pt" => "pt-BR", "zh" => "zh-CN" }.freeze

def resolve_locale(locale)
  return DEFAULT_LOCALE if locale.blank?
  return locale if supported?(locale)
  return LOCALE_ALIASES[locale] if LOCALE_ALIASES.key?(locale)

  base = locale.split("-", 2).first   # "fr-FR" -> "fr"
  return base if supported?(base)

  DEFAULT_LOCALE
end

A CI test asserts every one of the 42 catalogs has exactly the same flattened key set as en.yml, every value is non-blank, and every {{interpolation}} placeholder in English survives in the translation. That parity test turns "did I remember to update all 42 files?" from a code-review prayer into a red build.

Sparse overrides

The shop_translations table has a unique index on (shop_id, locale, key) and one rule that shapes everything: defaults never get copied into the database. A row exists only when a merchant changed something. Clearing a field deletes the row:

if value.to_s.blank?
  scope.delete_all
else
  ShopTranslation.upsert(
    { shop_id: shop.id, locale: locale, key: key, value: value },
    unique_by: %i[shop_id locale key]
  )
end

This keeps the table tiny (most shops have zero rows), means updated default copy ships to everyone on deploy with no backfill, and gives the admin UI a free "Default vs. Customized" badge — a row's existence is the customization state.

The merge is then one expression:

translations = overrides.empty? ? defaults : defaults.merge(overrides)

Caching against the grain of the platform

Translations are read-heavy, so the instinct is "put it behind a CDN." Two Shopify constraints break that:

Session tokens rotate every ~5 minutes and travel in the Authorization header. HTTP caches key on the request — a rotated token is a new cache key, so browser Cache-Control and CDN caching are guaranteed misses. Cross-customer hit rate is zero by construction (every customer has a unique token).
The extension sandbox has no localStorage and no service workers. The only client-side persistence is JavaScript module scope — survives component re-mounts, dies on full page reload.

So instead of one big cache, three small layers.

Layer 1 — process memoization. YAML files are static between deploys, so the loader memoizes the parsed-and-flattened result in a class-level hash. One subtlety: the result is a Data.define struct, and Data freezes the struct but not the hash inside it. Without an explicit .freeze on the translations hash, any caller could mutate the shared cached copy for every subsequent request in that process.

Layer 2 — Redis for the merged payload. With YAML in memory, the expensive repeated work is the Postgres query confirming "this shop has no overrides" — which is the answer for most shops on most requests. We cache the merged result per translations:merged:{shop_id}:{locale} with a 1-hour TTL. The key uses the resolved locale, so pt, pt-anything, and pt-BR all share one entry instead of proliferating keys.

Layer 3 — client-side skip. The extension keeps the translation map in module scope and records which locale it loaded. On re-mount (customers bounce between order pages more than you'd think), it skips the fetch entirely:

const translationsPromise = isLocaleLoaded(locale)
  ? Promise.resolve(null)
  : fetchTranslations({ backendUrl, locale, sessionToken }).catch(() => null);

The .catch(() => null) matters. Translations load in a Promise.all alongside the order-actions request, and a translations failure must never block the whole block from rendering — the extension degrades to its bundled shopify.i18n.translate copy instead.

Invalidation: the callback that would never fire

My first instinct for cache invalidation was an after_commit callback on the model. It would have compiled, looked correct in review, and never fired once — because both write paths use upsert and delete_all, which bypass ActiveRecord callbacks entirely.

Worse than not working, a callback would actively mislead the next developer into assuming invalidation is automatic. So each write site calls the bust explicitly after its transaction commits:

Translations::MergeLocaleService.bust_cache(current_shop, locale)

Less magic, impossible to misread. The merchant who saves a translation and immediately previews the extension sees the new copy.

The cache that never hit

After shipping Layer 3, everything worked — copy rendered correctly in every language. But for some locales, the client-side cache never hit. The extension re-fetched translations on every single mount, and nothing in the UI looked wrong.

The cause: the client and server speak different locale dialects. Shopify reports the customer's language as, say, pt. The server resolves that to pt-BR and returns the resolved locale in the payload. My skip-check stored the server's value:

// before: stores "pt-BR"
markLocaleAsFetched(response.locale);

// next mount: client asks about "pt"
isLocaleLoaded("pt")  // "pt" !== "pt-BR" → miss, forever

For any aliased locale, the cache could never hit. And because a miss just means "do the fetch," the failure was invisible: correct output, wasted requests.

The fix clarified something I'd been conflating — there are two locale values with two different jobs. translationsLoadedForLocale must store the client-side locale, because its job is cache identity: "did I already fetch for what the client is asking?" A separate serverLocale stores the server-resolved locale, because its job is plural selection. Which brings me to —

Pluralization doesn't come for free anymore

shopify.i18n.translate handles plurals automatically from the bundled JSON structure. The moment you serve a flat key-value map from your own server, you've opted out of that, and nobody warns you. "1 Day" / "3 Days" quietly breaks.

The catalog stores plural forms as separate keys (time.days.one, time.days.other), and the client helper reimplements selection with the platform primitive:

if ("count" in params) {
  const form = new Intl.PluralRules(serverLocale).select(params.count);
  const pluralRaw = serverTranslations[`${key}.${form}`];
  if (typeof pluralRaw === "string") return interpolate(pluralRaw, params);
}

Note serverLocale — the resolved one. Intl.PluralRules needs to know it's doing Brazilian Portuguese plural rules regardless of what the browser reported. The same normalization that broke my cache is load-bearing for plurals.

Decisions worth calling out

A few choices that punched above their weight:

Two-phase rollout for the contract change. The extension previously read its labels from the order-actions endpoint. PR one made the extension read from the new translations endpoint while the old endpoint kept shipping the copy nobody read — dead payload, instant rollback if anything broke. Only after that baked in production did PR two strip the copy server-side.
One deprecated field survived the cleanup. The extension and backend deploy independently, so an old extension version can hit a new backend. We kept label in the order-actions payload as a fallback for stale clients; removing it is its own ticket, not a rider on this one.
Interpolation validation at write time. If the English source contains {{count}}, a merchant's override must too — otherwise the save is rejected with the missing placeholders listed. Catching this at write time beats a customer seeing a literal {{count}} on their order page.
The Customize tab and Localization page share rows via one mapping module. A single KeyMapping constant is the source of truth for "this Customize-tab field is that translation key." Edit a label in one surface, the other shows it customized. No sync logic, because there's nothing to sync.
The admin editor classifies rows as short, long, or plural and renders the right input for each — plus highlights {{interpolation}} tokens as non-editable segments, so merchants can't accidentally translate a variable name.

What's next

The three cache layers are holding, but the escape hatches are documented if load outgrows them: a public no-auth URL for shops with zero overrides (CDN-cacheable), or metafield delivery as the nuclear option.
Generating the extension's bundled fallback JSON from the server YAML in CI, so the two can't drift.
Removing the deprecated label field once old extension versions age out.

The feature is live across 42 locales — 378 keys each, roughly 15,800 translated strings — with merchants able to override any one of them per language.

Thanks for reading. If you've built on Shopify customer account extensions: how did you handle the rotating session tokens? The "your auth design makes HTTP caching impossible" constraint felt like the most underdocumented part of the platform, and I'd love to hear how others worked around it.

Building a Conditional Fee Engine for Returns: How We Stopped Refunding Cash

hans — Thu, 07 May 2026 03:18:00 +0000

When a customer returns a $50 item with a $5 restocking fee, who actually pays the $5?

In most returns systems, the answer is: the retailer does. The customer gets $45 back to their original card, and the $5 the retailer was supposed to recover never lands anywhere — it's just absorbed into the refund. Multiply that across thousands of returns a month and the leak adds up to real money.

This is the story of how we fixed that at PostCo.

Context

PostCo is a returns management platform that sits between Shopify retailers and their customers. When a customer returns an item, we orchestrate the whole flow: validating the return, calculating refund amounts, picking the right refund method, and posting the result back to Shopify.

For a long time, "fees" on returns were modeled as Return Amount Adjustments (RAA) — outcomes attached to PolicyRules, evaluated at return creation time, hardcoded to deduct from the original payment method. Retailers could configure them, but the system was rigid:

Adjustments were tied 1:1 with PolicyRule outcomes.
The deduction always came out of the refund the customer received in cash.
There was no way to apply a flat fee unconditionally, or scope a fee to "exchanges only," or split a fee across multiple refund methods.
Manual ad-hoc adjustments in the resolve modal didn't exist — every adjustment had to round-trip through the policy engine.

The Problem

Two business problems converged.

Retailer cash leakage. When a $50 return had a $5 restocking fee, the customer still got $45 refunded to their original card. The retailer never recovered the cash that went out the door. If instead the $5 came out of an existing gift card balance, the retailer kept the entire $50 in their ecosystem.

Configuration ergonomics. Retailers wanted a Fees page where they could say "all bag returns are charged 15%" or "all returns ship at $5" without learning the PolicyRule UI. They also wanted ops staff to slap an ad-hoc credit or charge onto a return at resolve time without reopening configuration.

The Solution

A new Return Amount Adjustment Preset system that:

Lives alongside RAA during rollout, gated by a return_fees_enabled shop flag.
Supports unconditional ("apply to all") or conditional (scoped to a PolicyRule) presets.
Distributes the fee across return methods in a priority order, only falling through to the original payment method (OPM) as a last resort.
Exposes a manual adjustment API for the resolve modal — POST/DELETE, sign derived server-side.
Provides a one-click migration from legacy RAA rules to presets.

Implementation

Data model

Two tables.

return_amount_adjustment_presets:

shop_id, title, amount_cents, unit ("percentage" or "amount")
apply_to_all (bool), policy_rule_id (nullable FK)
applies_to ("refund" or "exchange")

return_amount_adjustment_priorities:

one row per shop, JSONB array of return methods in priority order

The clever bit is the relationship with PolicyRule. Rather than build a parallel rules engine, we extended the existing one:

PRESET_OUTCOME_TYPES = ["Return Amount Adjustment Preset"]
VALID_OUTCOME_TYPES = [...existing, *PRESET_OUTCOME_TYPES]

validates_presence_of :outcome_values,
  unless: -> { outcome_type == "Return Amount Adjustment Preset" }

has_one :return_amount_adjustment_preset, foreign_key: :policy_rule_id

The outcome_values skip is the trick — preset rules store their data on the associated record, not in the rule's outcome_values JSON. That keeps the preset editable from the Fees UI without round-tripping through the policy engine.

Distribution priority

The core service, EvaluatePresetAdjustmentsService, builds an "adjustment pool" from all matching presets and distributes it across the customer's enabled return methods in this hardcoded order:

gift_card → discount_code → shopify_store_credit → original_payment_method

Why hardcoded? Because the PM wanted to validate the E2E flow before exposing the priority order as a configurable knob. Shipping the engine first and the configuration UI later was the lower-risk path. The priority table exists in the schema; the admin UI for it is deferred.

There's one safety guard worth calling out: orders sourced from Facebook can't receive adjustments routed to the original payment method, because that source can't honor a cash-back scenario.

adjustments.reject! { |a| a.return_method == :opm } if order.from_facebook?

Manual adjustments

The resolve modal needed a way to attach ad-hoc credits/charges without going through the preset engine. Two decisions worth highlighting.

Server-derived sign. The API takes type: "credit" | "charge" and amount_cents (positive integer). The sign is determined on the server based on type. Floats never enter the picture, and a malicious or buggy client can't flip a charge into a credit.

Manual flag to survive rebuilds. The UpdateService rebuilds preset-derived adjustments every time a return order changes. To prevent that rebuild from blowing away manual rows:

def existing_refund_adjustments
  return_order.return_amount_adjustments.where(manual: false)
end

Manual rows are invisible to the rebuild. Only preset/policy rows churn.

Exchange-side charges

Exchanges introduced a wrinkle: lower-value exchanges can produce a negative refund balance.

Customer exchanges a $50 item for a $30 item with a $5 fee → retailer owes them -$25 + needs to charge $5 = customer pays $5 via Stripe.

Two new attributes on ExchangeResource made the resolve modal math correct:

attribute :bonus_credit_cents      # extra credit awarded for the exchange
attribute :price_difference_cents  # delta between returned and incoming items

These get folded into the resolve modal's charge calculation so the displayed total matches what Stripe will actually charge.

Concurrent migration safety

The migration from legacy RAA to presets has a nasty race: if a return order is created mid-migration, it might evaluate against a return_fees_enabled shop with no presets yet — or worse, with both old RAA rules and new presets active.

The fix in CreateService and UpdateService:

shop.reload

if shop.return_fees_enabled?
  evaluate_presets
else
  evaluate_raa
end

A reload looks ugly. It is. But the cost of a stale association during a 30-second migration window is wrong fees on real returns, which is unrecoverable. The reload is cheap insurance.

Preview endpoint

The resolve modal needed live fee preview as ops staff toggle which items to reject. New endpoint:

POST /return_orders/:id/return_amount_adjustments/preview
{ scoped_item_ids: [...] }

The service evaluates presets against only the non-rejected items, returning unsaved adjustment instances for display. filter_merchant_deleted_adjustments removes adjustments tied to presets the merchant deleted after the return was created — important for historical accuracy.

UI choices worth calling out

A few small decisions that punched above their weight:

applies_to is a radio with two options ("refund" or "exchange"), not a "both" checkbox. The original spec had "Both" as a third option; we removed it because the two flows have different sign semantics (refunds deduct, exchanges charge) and conflating them confused early testers.
Tags are case-insensitive, even though Shopify treats them case-sensitively in some contexts. We lowercase both sides at compare time. Retailers tag inconsistently, and a strict comparison would silently miss matches.
Tag input saves on blur, not on every keystroke. Earlier behavior wiped the field when focus moved — a regression caught in QA. Now onBlur commits, onChange updates local state.
Delete preset surfaces a confirmation modal. Deletes are destructive (the preset is FK'd from historical adjustments via the policy rule), so we confirm before executing.
Resolve modal hides the manual adjustment UI for legacy RAA orders. Mixing manual rows into a return that was created under the old engine produces inconsistent totals. Easier to lock those returns to the legacy flow and only enable manual adjustments on preset-era returns.
Validation error UX uses fixed-height field containers so error messages don't shift modal layout when they appear/disappear. Tiny detail, big quality-of-life difference.

What's next

Configurable priority order (currently hardcoded).
Stripe charge for negative refund balances on the refund flow (the exchange flow already supports it).
Trend dashboards: how much retailers retain in store credit vs refund out as cash, which is the actual business metric we're trying to move.

The migration is rolling out cohort by cohort. Real numbers in a month or two.

Thanks for reading. If you've shipped something on a cash path before, I'd love to hear how you handled the migration race conditions — that part felt the most "anything could go wrong" of the whole project.

Bridging the Tracking Gap: Implementing Manual Returns for Retailers and Customers

hans — Mon, 16 Mar 2026 03:15:00 +0000

In the world of e-commerce returns, "Mail Returns" (where a customer ships a parcel themselves) are often a black hole. Because the system doesn't generate a label, there is no automatic tracking. No one knows where the package is, and the "he-said-she-said" over shipping proof becomes a support nightmare.

We recently tackled this by building a manual tracking flow that serves two distinct masters: Retailers needing oversight and Customers needing peace of mind. Here is how we built a unified tracking system across two different UIs with a shared backend.

The Problem: The "Mail Return" Black Hole

When a return is marked as Mail, the customer uses their own shipping method (e.g., national post or a local courier).

For Staff: They can't see when a return is coming or if it's even been sent.
For Customers: They have no way to "prove" they shipped it within the platform.
The Technical Gap: Since no label is generated by our system, no tracking data is auto-filled.

We needed a way for both parties to manually input Tracking Numbers and Courier Names into a shared source of truth.

The Architecture: One Logic, Two Gates

Instead of building two separate tracking services, we opted for a shared form object pattern. This ensures that whether a retailer updates a number or a customer does it, the validation and persistence logic remain identical.

1. The Backend Foundation

We leveraged a Shipment::UpdateForm object to handle the heavy lifting. This kept our controllers thin and our models clean.

Feature	Implementation Detail
Endpoints	`PATCH .../customer/shipment/tracking`	`PUT .../retailer/shipment_tracking`
Validation	Max 64 chars for tracking; Max 128 for courier; Alphanumeric only.
State Guard	Only allows updates if the return is in `pending` or `pending_action`.
Data Model	Updates `tracking_number` and `custom_courier_name` on the `Shipment` model.

Pro-Tip: Avoid heavy model callbacks. By performing the update within the Form Object’s submit method, we ensured that side effects (like invalidating cache) only happened when the form was actually valid.

The Frontend Implementation

Retailer Experience (React + Polaris)

In the retailer dashboard, we focused on speed and clarity for support agents.

Contextual UI: If the shipping method is "Mail," an "Add Tracking Number" button appears.
The Modal Flow: Clicking the button triggers a Polaris modal that pre-fills existing data if the agent is editing rather than adding.
Immediate Feedback: Upon saving, the app invalidates the return order query, triggering an instant UI refresh to show the new "Track" button (which links to the external tracking URL).

Customer Experience (Remix + React)

The customer-facing side needed to be more "walk-through" style. We integrated this directly into the Return Summary page.

Progressive Disclosure: We show the "Tracking Number" and "Courier" labels even if empty to signal that this information is expected.
Inline Editing: Instead of a modal, we used an inline form. The "Save" button remains disabled until both fields are filled to ensure data integrity.
I18n Ready: Since we operate globally, all labels (add_tracking_button_label, etc.) are served via the API to support multi-language storefronts.

Key Technical Takeaways

Shared Validation is King: By using a single Form Object, we prevented "data drift" where a retailer might be able to enter a character that a customer’s UI would reject.
Status-Awareness: Don't let users edit tracking after a return is "Completed" or "Cancelled." Hard-coding these guards into the service layer prevents API abuse.
The "Track" Button Logic: We implemented a fallback mechanism. The UI displays the custom_courier_name if present, but falls back to the system's courierName for legacy data, ensuring the "Track Shipment" link never breaks.

Final Thoughts

Manual tracking isn't just about adding a text field; it's about creating a reliable audit trail. By building a unified backend and tailoring the UI to the specific needs of retailers and customers, we turned a "black hole" into a transparent part of the return lifecycle.

Beyond Manual Coding: Implementing an Agentic CI/CD Workflow at PostCo

hans — Thu, 12 Mar 2026 03:15:00 +0000

In a high-growth startup environment like PostCo, the goal is always the same: Ship high-quality features, faster.

As a Junior Software Engineer, I quickly realized that traditional "manual" workflows—where every line of boilerplate and every initial refactor is typed by hand—are no longer the most efficient way to deliver value. Instead, I’ve been developing an "Agentic Workflow" that uses AI agents as force multipliers within our CI/CD pipeline.

The Problem: The "Boilerplate" Bottleneck

Most developers spend a significant portion of their day on repetitive tasks: setting up file structures, writing unit tests, or refactoring existing methods to fit new requirements. These tasks are necessary but often delay the critical "thinking" work.

The Solution: The 4-Stage Agentic Loop

Our workflow at PostCo is designed to automate the execution phase while keeping the "Intent" and "Quality Control" firmly in human hands.

1. Requirements and Context (Notion + Linear) Every feature starts with a deep dive. We use Notion for Implementation Docs that define the why and how. These are synced to Linear, providing a clear map for the development process.

2. Agentic Execution (GitHub + Claude) The moment a PR is created, a Claude Agent (Planner/Executor) analyzes the Implementation Doc and the existing codebase. It doesn’t just suggest code; it executes it, pushing a functional starting point to the branch.

3. The "Checker" Loop Code shouldn't just be written; it should be verified. We employ a second Claude Agent (Code Checker) that reviews the first agent’s work. They loop bidirectionally:

Executor pushes code.
Checker identifies logic gaps or style inconsistencies.
Executor refines the code.

4. The Human-in-the-Loop: Tech Lead Review Once the agents have iterated to a point of stability, the "Review" phase begins. I take the refined code and walk through it with my Tech Lead. This is where we discuss the "Big Picture"—scalability, edge cases the agents might have missed, and alignment with our broader engineering goals at PostCo.

By the time my Tech Lead sees a PR, the "noise" has been filtered out. The code is already linted, tested, and structurally aligned with the requirements. This allows our senior engineers to spend their time mentoring and architecting rather than correcting syntax or boilerplate.

In 2026, being a "good developer" isn't just about how well you write code—it's about how well you manage the systems that produce it. This agentic workflow is just the beginning of how we’re scaling our engineering efforts.

Syncing Rails Validations with Formik: A Practical Approach

hans — Tue, 10 Mar 2026 03:12:00 +0000

In many SaaS apps, we allow "placeholder" data during onboarding to reduce friction. But what happens when that data needs to be validated later? I recently tackled this at PostCo by building a bridge between our Rails backend and React frontend.

Key Technical Takeaways:

The Backend Validator: Don't just rely on presence: true. I created a PlaceholderValidator to check against specific strings like "Address pending" or "00000".
The Error Bridge: Formik expects a specific shape. I wrote a utility to transform Rails' errors.messages into a flattened object that Formik can consume, including a case-mapping layer.
The UX Trick: If a field has a placeholder, the user shouldn't have to delete it manually. I implemented a "clear on edit" utility that treats placeholders as "" in the UI, triggering immediate Yup validation.

Handling nested errors is messy, but a little bit of mapping logic goes a long way in making a Junior-built feature feel Senior-grade.