Tutorial: ship your first change

By the end of this you’ll have run the broker app locally, made a real change to the leads UI, verified it in the browser, and opened a merge request — the whole loop, on a change that never touches the CRM. Budget ~45 minutes.

Your ticket: The column labels on the My-Deals cards (“Verification Date”, “Phone Number”, “Destination”, “Deal Status”) are hardcoded English and don’t translate. Make them use t(). It’s real, it’s safe, and you can see it by loading one page.

Note

New to the flow? Skim Broker submits a lead first — you’re editing the read side (the leads list), which the flow page introduces.

Prerequisites

• Node v20.19.2 (the repo pins it in .nvmrc; CI builds on Node 22 — match .nvmrc locally).
• Yarn 1 (classic).
• Read access to the frontend repo, and a broker test account for staging (ask your lead).

1 · Run the broker app

1. Clone and install:

   git clone <frontend-repo-url> frontend && cd frontend
   nvm use            # picks up .nvmrc → v20.19.2
   yarn install

2. Point the broker app at the staging API. Nx loads the repo-root .env into the build — an app-level .env is not picked up here — so copy the root example:

   cp .env.example .env        # at the frontend repo root

   The broker vars are already in it; just make sure they point at staging:

   NX__BROKER_API_ENDPOINT=https://api.orascom.robustastudio.com/api
   NX__BROKER_ENDPOINT_PREFIX=/broker

3. Start it:

   yarn start:broker        # http://localhost:4201

4. Log in. The broker portal uses email + password. Sign in with your broker test account. If a redirect gets in the way, the reliable shortcut is to log into staging in another tab, copy localStorage['broker_access_token'], and set the same key on localhost:4201 — then reload.

Tip

You’re pointed at the staging API, so you’ll see real staging data. That’s fine for this tutorial — you’re only reading the leads list. Don’t submit deals here unless you mean to (a submit writes to the production CRM).

2 · Make the change

Open apps/orascom-broker-app/src/components/deal-card/deal-card.tsx. Around lines 61–81 the labels are hardcoded strings inside styled paragraphs:

// before
<p className={styles['label']}>Verification Date</p>
<p className={styles['label']}>Phone Number</p>
<p className={styles['label']}>Destination</p>
<p className={styles['label']}>Deal Status</p>

This component doesn’t import the translation hook yet — add it (copy the pattern from new-deal.tsx):

import { useTranslation } from 'react-i18next';
// …then, at the top of the component body:
const { t } = useTranslation();

Now wrap each label — keep className={styles['label']} or you’ll drop the styling:

// after
<p className={styles['label']}>{t('verificationDate')}</p>
<p className={styles['label']}>{t('phoneNumber')}</p>
<p className={styles['label']}>{t('destination')}</p>
<p className={styles['label']}>{t('dealStatus')}</p>

Then add the missing keys. phoneNumber already exists in both locales, and destination exists in en only — so you add two keys to en and three to ar (Arabic is a partial stub; any key you miss falls back to English, which is the exact bug you’re fixing):

// public/locales/en/translation.json  — add these two
"verificationDate": "Verification Date",
"dealStatus": "Deal Status"

// public/locales/ar/translation.json  — add these three (destination is missing here!)
"verificationDate": "تاريخ التحقق",
"dealStatus": "حالة الصفقة",
"destination": "الوجهة"

3 · Verify it

1. With yarn start:broker running, open http://localhost:4201/my-deals. The cards still read correctly in English — you didn’t break anything.
2. Flip the language to Arabic (the language switcher is gated by NX_SHOW_LANGUAGES_OPTIONS; set it true in your .env if hidden). The labels now render in Arabic instead of hardcoded English. That’s the fix, visible.

4 · Lint, type-check, test

yarn nx lint orascom-broker-app
tsc -p apps/orascom-broker-app/tsconfig.app.json --noEmit   # plain `tsc --noEmit` checks nothing in this Nx app

Both must pass — SonarQube is a blocking gate in the frontend pipeline, and the pre-commit hook runs lint-staged (eslint + prettier). Fix anything they flag before committing.

5 · Open the merge request

This repo is on GitLab — you open a merge request (MR), not a GitHub pull request.

1. Branch and commit using Conventional Commits (a commit-msg hook enforces it):

   git checkout -b feat/broker-translate-deal-card-labels
   git add -A
   git commit -m "feat(broker): translate My-Deals card labels"
   git push -u origin feat/broker-translate-deal-card-labels

   Heads-up: a pre-push hook builds all four apps (nx run-many --target=build --all), so the first push is slow and rejects the push if any app fails to build.
2. Open a merge request against develop (the default branch; develop auto-deploys to staging on merge). CI runs sonarqube-check (blocking) → build. Get a review, merge.
3. After merge, verify on the staging broker portal that the Arabic labels render.

What you just learned

• The frontend dev loop: nvm use → yarn install → yarn start:broker → change → lint/type-check → PR.
• The i18n gotcha that recurs everywhere: the broker app ships ar + en, and ar is a partial stub — so any key you miss silently falls back to English.
• The branch model: develop → staging, and the blocking SonarQube gate.

Ready for a deeper change?

Do the Add a field to the lead form how-to next — same loop, but it crosses all three repos and coordinates with the CRM team.