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 pull 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 22 (the repo pins it in .nvmrc on uat; nvm use picks it up, and CI and Amplify both build on 22). Note main still pins v20.19.2 — if you are working from a main checkout you will get the old pin.
• Yarn 1 (classic).
• Read access to the frontend repo, and a broker test account for UAT (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 → 22 (on uat)
   yarn install

2. Point the broker app at the UAT 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; make sure they point at UAT:

   NX__BROKER_API_ENDPOINT=https://api-orascom-uat.my.orascomdh.com/api
   NX__BROKER_ENDPOINT_PREFIX=/broker

   Two variables you may see referenced elsewhere but should not add: NX_CLIENT_SECRET and NX_FIREBASE_API_KEY are unset in every environment and unread by app code.

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 UAT at https://odh-uat.my.orascomdh.com/partners in another tab, copy localStorage['broker_access_token'], and set the same key on localhost:4201 — then reload.

Tip

You’re pointed at the UAT API, so you’ll see real UAT 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. On the pull request, the frontend’s required check is checks — within it lint and build block a merge; the test target does not (it runs with continue-on-error). The pre-commit hook also runs lint-staged (eslint + prettier). Fix anything they flag before committing.

5 · Open the pull request

The frontend now lives on GitHub (OrascomDevelopment/Orascom-Portals-Frontend) — you open a pull request (PR), not a GitLab merge 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 pull request against uat — that is the base branch and the GitHub default. Your PR needs the required checks job to pass and one approval before it can merge. The frontend deploys on AWS Amplify with branch-level autoBuild, so on merge to uat Amplify builds and deploys automatically — no manual deploy step. Expect 4–6 minutes.
3. After merge, verify on the UAT broker portal — https://odh-uat.my.orascomdh.com/partners — 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: uat is the base branch, main is production, and the frontend ships via Amplify autoBuild on merge (no manual deploy). develop still exists but is retired and frozen — pushing to it is blocked outright, because the branch is locked read-only. Your commits stay safe locally; git simply refuses the push. The environments and their URLs are on Environments; the whole rail is on How deployment works.

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.