Skip to content

Localization Process

Jump to bottom
lmarceau edited this page Jan 27, 2023 · 45 revisions

Overview

The following document gives a step by step guide for the string localization process.

Important note

Be aware that manual string import and export shouldn't be done anymore. They both need to happen through Github actions.

Github action import process

Import

String import from the firefoxios-l10n repository happens once a week and points to the main branch. The Github action opens a PR, which then needs to be reviewed and merged by the developer team. Importing strings can also be done by pointing to a certain branch. For example, on hard freeze a string import can be triggered by running the Create a PR with changes after importing strings workflow, and writing down the targeted version of the branch as shown in following picture:

Screen Shot 2022-09-12 at 1 36 19 PM

Export

String export happens by adding new strings into the Firefox for iOS strings file. Any developer adding new strings to the project should be familiar with the principles described in l10n documentation.

Steps to add strings to the strings.swift file:

  1. Add the version of your new strings in StringLastUpdatedAppVersion if it doesn't exist yet.
  2. Add the new strings in the related struct. If there's no struct for a string, create one related to the feature or section this string will be under.
  3. How to define a localized string can be found here.
  4. Once all strings are added, open a PR on Firefox for iOS.
  5. Once merged, the new strings will be exported automatically to the firefox l10n repository through the automated Github action. In case the export needs to be triggered sooner, ping Delphine so the export Github action can be triggered.

Manual String import process

⚠️⚠️⚠️

Shouldn't be done anymore, use Github actions instead. Keeping this documentation here for now in case it would be needed.

⚠️⚠️⚠️

Requirements for manual string import

This following repos are the required to run the localization process.

A note on this process. If you run sh ./bootstrap.sh --importLocales this will bootstrap the main Firefox-iOS repo and also download the localization tools and l10n repo in the firefox-ios folder and you don't have to do it manually.

You can also do this manually, of course. Either way, note the location of the l10n repo as you will need it later.

Manual Process Overview

  1. Pull firefoxios-l10n so master is up to date
  2. Create separate branch off main in firefox-ios
  3. Import strings
  4. Make a PR to main and merge when approved
  5. Create a new branch from main and add new strings
  6. Export
  7. Make a PR to master in firefox-l10n from your fork
  8. Admin will merge
  9. Wait for translations to come in and be notified
  10. Pull master from `firefoxios-l10n'
  11. In your string branch on the firefox-ios repo, do an import
  12. Make a PR to main

Manual Setup

Now that you have everything you need, here are the steps you need to take for localization.

  • When you begin the process always pull the latest firefoxios-l10n master branch. This ensures that you have the latest strings from translators before you do an export and prevents discrepancies when we're exporting.
  • Open the LocalizationTools project. If you have an error, you might need to adjust the swift-tools-version, located in Package.swift. Either upgrade or downgrade it depending on your swift-tools-version. As of Sep 2021, 5.4 will work fine.
  • Now, click Edit scheme and select the Run scheme.
  • Add arguments to the scheme to configure what you're doing
  • --project-path "project-path" Sets the project path to firefox-ios. This should point to wherever your Client.xcodeproj is, and specify the project file in the path as well. You should write the full path to the Client.xcodeproj, which can be found using pwd command in a terminal.
  • --l10n-project-path "l10n-project-path" Sets the path to the firefoxios-l10n repo. You should write the full path to the firefoxios-l10n repo, which can be found using pwd command in a terminal.
  • --export/import Depending on whether you want to run an export/import task
  • --version show the version
  • --help show help information

Manual Imports

Note: Even if your goal is to export, you still need to import first. This ensures that string translation fixes for existing strings are present during the export.

After setting the arguments above, let it run with the --import argument. Importing will take a while. Be aware that you'll see lots of errors & warnings in the console. You can ignore these - it won't affect your import process.

After the process is complete, you'll see a list of files modified in your firefox-ios repo. If your goal was to import newly available/translated strings, you can commit the necessary files and create a PR on firefox-ios.

Import runs, but there are no changes on the firefox-ios repo

One reason this may be happening is because of how Xcode is named on your system. If you have multiple versions of Xcode, you may have named them Xcode 13.0, Xcode 12.4 etc. In the logs, look for:

Command line invocation:
    /Applications/Xcode 13.0.app/Contents/Developer/usr/bin/xcodebuild -importLocalizations -project ...

The Xcode part of the command line invocation, in this example, should be /Applications/Xcode\ 13.0.app/... but it seems that it doesn't get called correctly. You must rename your Xcode, in this situation, to not have a space - Xcode13.0 in this example. This should fix the problem and allow you to import successfully.

Manual Exports

Note: Imports need to happen before you do an export! Follow the process above and come back here after.

  • Be sure that new string comments are understandable to localizers. Make sure comments are descriptive and don't rely on knowing the context of the new string.
  • Here, we'll switch to the --export argument
    • Importing will result in changes in firefox-ios. Exporting will result in changes in firefoxios-l10n.
  • Each locale modification will need a separate commit. You can use this bash script (for now)
#! /usr/bin/env bash

l10n_file="firefox-ios.xliff"
locale_list=$(find . -mindepth 1 -maxdepth 1 -type d  \( ! -iname ".*" \) | sed 's|^\./||g' | sort)
for locale in ${locale_list};
do
    git add ${locale}/${l10n_file}
    git commit -m "${locale}: Update ${l10n_file}"
done
  • Push your branch to your fork
  • Make a PR to firefoxios-l10n repo master
  • Once the PR has been approved, merge
  • Once we are notified that the strings have been translated, we'll have to do another import on a branch off of main in the firefox-ios repo
  • Make a PR and double check that everything shows up correctly

You have now achieved expert level status on String Localization. Rejoice. Celebrate! Do a victory dance!!!

Addressing Comments

Ahh, you're back. I expected you. L10N team gave you some edits and you're wondering what's the best way to fix and push? The gist is that you have to redo the export process and force push. Here are steps:

  • Find the last commit on master before all your commits were added on the L10n repo.
  • To delete commits up to that commit, run git reset --hard <commit-hash>.
  • With your fixes now ready (made in the Firefox-iOS repo), run the export and the bash script again.
  • Force push to your branch.

Notify the L10N team about updates!

Clone this wiki locally