• Find the Black Mesa folder the game is installed in.
  
• Find the bms_misc_dir.vpk in
  ...\steamapps\common\Black Mesa\bms
  This file loads the resource text and scripts, and we'll need those files to get started.

Open up your folders so that you can drag the bms_misc_dir.vpk file onto vpk.exe.
A folder called bms_misc_dir will be created in ...\Black Mesa\bms

Using GCFScape, you can open a _dir.vpk file, then specify what files to extract from it.

NOTE: When the game is updated, repeat this step to get the latest update files for your translation mod!

• Choose a location to create your folder, and name it whatever you want.

When you compile it as a finished mod, it will have the name folder name and a .vpk extension.

• Make a folder inside it called 'resource'
  
• Go to where you extracted the bms_misc_dir files.
  You're most likely basing the translation on the _english.txt files, but if you want easy access to other language-files you can grab them now if you want.

bms_lang.txt
bmsmp_lang.txt
bootup_lang.txt
closecaption_lang.txt
credits_lang.txt
crowbarcollective_lang.txt
gameui_lang.txt
gameui_loading_screen.txt


This is for adding extra features to your mod


theme.qml

theme.qml - This will override how time and date is displayed for save games.
logo.png
logo-new.png

logo.png, logo-new.png - Editing these changes the game title logo on the main menu.
Personally, I only edited 'logo-new.png' in my translation. (It displays when first starting the game / loading it up with an empty saves folder.)


credits.txt

credits.txt - This is used for if you want to add a section in the ending credits

Same as 'ui' and theme.qml. Grab these files from the extracted bms_misc_dir
directory:

l10n.qml
routeview-audio.qml

l10n.qml, routeview-audio.qml - These are for adding a selectable subtitle option to the menu.
NOTE: If you don't use this method, subtitles can only be activated with the in-game cc_lang console command. Example:
And if the mod has a closecaptions_swedish.dat, it will read from that.

The way Black Mesa works currently, as of Release 1.0, your day and month format is read based on what language you launch the game through... I think.
So if your langauge wasn't selectable in base-game, you'll have to overwrite some code to make it work.

Here's is the current time and date code:

Replace that text with the string for your langauge with this code:

For example

To do this, edit /scripts > credits.txt and /resource > credits_english.txt
and add new code strings - check the image for a reference.

Looks like this in-game
(To add a space under 'Jake Weitzman' in the credits, take out the // from the first #Blank command in this section's reference image.)

Edit the .png files in your resource folder with the program of your preference.

custom logo-new.png in-game (remember to load the game with an empty /saves folder to see this!)

Navigate to the bottom of routeview-audio.qml and find the part with label-language values.
Add another row of code for your new "language button". (Replace ___ with your language)

Open l10n.qml and navigate to the bottom and find the language get-string values.
Add another row of code. (Replace ___ with your language)

Lastly, open up the crowbarcollective_english.txt file in /resource and find Option_Language part. (Near the lower-middle of the file.)
Add another row of code. (Replace ___ with your language)

How the new "language button" should look in-game.

It is heavily recommended you have the notepad++ program installed for this.
Okay! Now we're on to the 'fun part' of this process.
Just know that it will take alot of time. (Atleast if you do it all by yourself.)

Pro-tip: The 'triple space' blocks that seperate lines in the strings can be added yourself by pressing [TAB].

Don't be afraid to try out the translation mid-way through writing it, as seeing it applied can be very motivating. - Go to the 'Testing the text in-game' section to see how that is done.

If you're like me, you eventually go back and change things around numerous time when text stuff in-game. It's very tempting to keep tinkering with a translation forever.

"There's this problem that when you work on games [...] everything is abandoned in the end, and its a collection of flaws and regrets." - Gabe Newell in IGN's Half-Life Alyx review. (20:30)

If you're fluent in/want to google translate more than one language, you can reference other lang.txt files for translation choices, if you find yourself stuck on a tricky sentance. E.i., making it not sound forced/broken/too literal.

Some sentences might be missing punctuations / marks. Start without a capitalized letter.
Start without two capitalized letters.
Some sentences with a space after the first qoute. Some sentances with double spaces.
NOTE: In some parts thats intentional / a style choice. - Your matter of preference decides if it stays in.

This is the only place you can find what the 'Stun Stick' is called in your langauge.
As well as terms like; 'Frag limit', 'Time limit', 'Server name', etc.

Boot up HL:S or open its resource folder and borrow stuff like;
- Chapter titles, including the 'Hazard course', which the opening guard mentions.
(For my language, Swedish, it was literally called 'The obstacle course')
- Tramride, Game over, and Endgame text scrolls.

Is Half-Life 2 translated into your language? To add extra consitency points to your translation, use those translation choices as a reference!

I found it useful when deciding on;
- Enemy names
- HEV suit terminology ('Hazard suit' name, Mark V or 'version' V...)
- Weapon CC choices (Subtitles like the, [Double Shotgun Blast!] one.)
- Options menu names
- ...And more!

• Option 1 - Find the HL2 'resource' folder.
  
• Option 2 - Play Half-Life 2 normally, and get to the parts you're curious about.

You can measure a translation on a scale of; 'Literal translation', and going into 'Liberal word choice + Localization based on scene context.'
The text being too literal can come of as stale, but it will definitively be faithful to the original's intent and tone.
The text being localized is done for the purpose of coming of as natural in the native language, but at the cost of maybe not matching the english dialogue properly, and adding/losing intent, implications and nuance of the original.

"Translation is tricky. With slightly altered lines often giving a scene a different tone or intent to the original." - Mistakes in Sonic Games - Did You Know Gaming? Feat. Remix (5:30)

- CHAPTER 01 - INBOUND
• 8:47 AM = 8:47 in the morning (12-hour to 24-hour times)
  
• 93 degrees ... 105 [degrees] ... 68 degrees = 31 degrees ... 40 degrees ... 22 degrees (fahrenheit to celsius)
  
• Urinalysis = (alternative) drug test
  
• This evening at 1900 hours = tonight at 19:00
  
  - CHAPTER 02 - ANOMALOUS MATERIALS
  
• Barney's been pretty scarce around these parts = I feel like Barney hasn't been here for a long time
  
• Put some pep in that step = (rough meaning) hurry up
  
• You're on sundial and we need you on stopwatch = (rough meaning) you're late and we need you now
  
• Quit busting my balls, already = (rough meaning) stop doing that, please
  
• I've already made plans = (alternative, in this context) But I had already made plans though
  
• This chicken scratch = this unreadable handwriting / scribbling
  
• You don't want me to write you up, do ya = you don't want me to report you, right
  
• Your sugarcoated ersatz are absolutely full of it = your pompous excuses are insufferable
  
• I too thought I was ''♥♥♥♥ of the walk'' when I first entered = I also thought I was the smartest when I started
  
• The halcyon days = good old days
  - Make the breakroom "atom and split" pun-guard either literal or straight-forward
  - Example: Make like traffic, jam
  - Example: Make like traffic, goodbye / go away / etc...
  
• Count your lucky stars = (rough meaning) see yourself as a lucky person / its good you didn't have to deal with that
  
• Certainly flatters your fundament = (rough meaning) looks good on you (literal meaning) it fits your back very tightly / makes your back look good
  
• You're in the barrel today = (rough meaning) it's your turn to do something unpleasant (alternatively) it's your turn in the barrel today
  
• Grab a cold one = get some beers (many languages might have 'cold ones'-type slang though)
  
• I'll keep ya posted = I will keep you up-to-date / keep you informed
  
• A man of facta, non verba = A facta, non verba-guy / [...] non verba-type guy
  
• Cover for your tardiness = explain away / act because of your delay / your lazyness
  
• Holding up the entire lab = delaying the entire lab
  
• Bit of a gamble = it's risky
  
• Certainly bolster your curriculum vitae = surely boost your noteriety / increase your merits / make you famous
  
• Radiation level is off the charts = it can't be measured / the scale isn't big enough to measure it
  
• Abide these perfunctory tasks = have the strength / the energy to deal with these boring tasks
  
• No time for cold feet = don't get nervous now / its not suitable to quit now
  
• Opening night jitters = (roughly) nervous / scared that it's finally happening
  
• The higher-ups will have our heads = we'll get fired
  
• Sustaining sequence = (alternative) continuing as planned
  
  - CHAPTER 03 - UNFORSEEN CONSEQUENCES
  
• I've... soiled myself = (alternative) I've... pissed myself
  
• Sordid business to attend to = filthy / unclean mess to fix
  
  - CHAPTER 04 - OFFICE COMPLEX
  
• Seventy-five mile radius = 40 kilometer radius
  
• Sustenance, beverages = (roughly) food, drinks
  
• Scintillating conversation = glowing discussions / stimulating talk
  
• So much for wishful thinking = (in this context) I was hoping that might work (roughly) it was worth trying
  
• Don't sweat it = don't worry about it / its okay on my end
  
• Happy trails = (roughly) I hope you're at peace / rest in peace
  
• Shut your trap = shut up / quiet (literal) close your mouth
  
• A more commodious rescue squad = a more qualified rescue team
  
• Secure access transmission = (alternative) secret radio broadcast
  
• I failed physical education = (roughly) I didn't pass school sports class
  
• Get a good running start there = (in this context) brace yourself before you leap / get enough room to make the jump
  
  - CHAPTER 05 - WE'VE GOT HOSTILES!
  
• They're coming for us = (alternative) they're chasing us
  
• So much for the goverment = the goverment has let us down / has betrayed us
  
• No delusions that this shall get any easier for you = I'm not gonna pretend / lie to you that this will get any easier for you / from here on out
  
  - CHAPTER 06 - BLAST PIT
  
• 9:47 a.m., Mountain Standard Time = (alternative) 9:47, MTZ
  
• Expired at 12:01pm, Mountain Standard Time, this afternoon = (alternative) became outdated at 12:01, MTZ, this afternoon
  
• 150 mile radius = 250 kilometer radius
  
• No sign of Smithers then = (alternative) so, you didn't see Smithers
  
  - CHAPTER 07 - POWER UP
  
• Stick around and help any other stragglers = (roughly) stay here and help anyone else who comes after you
  
• Hitting the books while the other one was chasing tail = (roughly) studying while the other was attempting to get / busy getting laid
  
• Smooth sailing = (in this context) our problem will dissapear
  
  - CHAPTER 08 - ON A RAIL
  
• Clear your dance card = prepare yourself / make yourself ready
  
• He was at ''Ground Zero'' = (alternative) he took part in what caused this (roughly) he was one of the ones who did this
  
• Think this guy's responsible = (alternative) do you think he did it purposefully?
  
  - CHAPTER 09 - APPREHENSION
  
• The Challenger Deep = Mariana Trench
  
• Terrestrial waters = earth waters
  
• More than welcome to try = you're fully welcome to try it yourself
  
• Sap your suit power = drain your suit energy
  
• Bent on reaching = fully intend to reach
  
• Give them what for = (roughly) give them a round of beatings / show them what you can do
  
• (Hgrunt rushes the player) = (alternative) (HECU-marine tackles you)
  
  - CHAPTER 11 - QUESTIONABLE ETHICS
  
• A few scientists hiding out somewhere = (alternative) there should be some scientists somewhere here
  
• Doesn't look like the front door is an option = it seems we can't use this door
  
• I don't think going in the front way is an option = -||-
  
• Goateed goliard = (rough meaning) bearded apprentice / pupil (literal meaning) bearded latin cleric
  
• Close shave = that was a close one
  
• Look what you did = (alternative, in this context) to think you survived / I don't believe it
  
• I... Can't believe what you did = (alternative, in this context) I... can't believe you survived / -believe you did it
  
• Many of our peers = many of our collegues
  
• Good luck. And Godspeed. = good luck. and good luck. (alternative-ish) good luck. and good succeed. (rough meaning of godspeed. simply tweak it to fit better when in other languages. or do what norway did, and just say 'good luck' once.)
  
• Running pell-mell = (roughly) don't rush in without thinking / unprepared
  
• It's much too unpredictable = (alternative) sadly it can't be relied on
  
  - CHAPTER 12 - QUESTIONABLE ETHICS
  
• Stay tuned to frequency 740AM = (alternative) keep yourselves informed on AM-frequency 740
  
• Simply lost my nerve = (roughly) I got way to scared
  
• Hey! HEY! = (alternative, in this context) Ouch! OUCH!
  
• Theoretical Proctologist = rectal theoretician
  
• Weapons lock-up = weapon storage
  
• The mother lode = (alternative) the gold mine / the jackpot / the big-time / etc...

Steam guides have a character limit for how much text a section can have. I... didn't know that. Oh well.

- CHAPTER 12 - SURFACE TENSION, continued

• Round up a posse = (rough meaning) rally up some freedom fighters (literal meaning) organize some justice people
  
• Sure pissed them soldiers off somethin' fierce = (roughly) made the military extremely angry
  
• Buzz us in, will ya = let us in
  
• Let things die down a bit = let things calm down first
  
• We cannot take off, we are grounded = we can't drive away, we are stranded
  
• Enemy air incoming = (alternative) incoming enemy airstrike
  
• Back up = retreat / get away
  
• For about half a mile = nearly a kilometer (half a mile = ~804 meters)
  
• I've had MY fill of ''fresh air'' = (alternative) that's enough ''fresh air'' for me now
  
• Make a break for it = (roughly) we'll run as fast as we can there
  
• Just Floor It = (alternative) just run
  
• Get your heart pumpin' = (alternative) what an adrenaline rush
  
• Tourniquet = (rough meaning) detachable bandage / tighly-pressed belt
  - LZ = Landing Zone
  
• Is anyone reading this = is anyone hearing me
  
• Blow it = detonate it
  
• we are pulling out = we are retreating
  
  - CHAPTER 13 - FORGET ABOUT FREEMAN!
  
• Cutting our losses = (roughly) stopping our losses from increasing
  
• (Screams of impending doom) = (alternative) (surprised death yell)
  
• [Mortar Above Ground] = [bombs exploding above ground]
  
• WAY behind enemy lines = deep into enemy territory
  
• Last flight out of here = last ride away from this place
  
• Poindexter = (roughly) nerd
  
• That doesn't involve swimming through ♥♥♥♥ and leeches = (alternative) an exit without ♥♥♥♥ and leeches to step on
  
• You good for nothin' = (roughly) you worthless little
  
  - CHAPTER 14 - LAMBDA CORE
  
• Scoured the area = (rough meaning) secured the area (literal meaning) cleared out the threats in this area
  
• You're not authorized to know about those = (alternative) at your clearance level you shouldn't know about those
  
• May be willing to donate his experimental weapon to your cause = (alternative, very liberal translation) I believe he wanted to give you his experimental weapon to aid in your mission
  
• Not the time to lose your nerve = Not the time to back down / get scared and quit
  
• Were you in weapons research too = (alternative) Were you also in the weapons department
  
• Put her to good use = (roughly) make sure she becomes useful / don't neglect using her
  
• Sight for sore eyes = (roughly) a beautiful / refreshing sight
  
• Take the access pipe = (alternative, in this context) swim through that access pipe
  
• The only one who possibly could = the only one who can do it
  
• Those jarheads = (roughly) those military dudes / gang of militaries
  
• A freakin' ZOO up ahead = (alternative) an absolute JUNGLE up ahead
  
• Until the gun goes click = until the magazine is clicking
  
• You're the one from the Anomalous Materials lab = (alternative) aren't you the man whose in Anamolous Materials
  - The old married couple joke is tricky. Try googling up synonyms for 'old', and get a word that fits into all three sentances.
  - These two bicker on like an old married couple
  - We ARE an old married couple
  - What do you mean OLD
  
• [Blows smoke] = [Unimpressed]
  
• Thought you'd never make it = (alternative) I never thought you'd make it / survive the way to here
  
• Pfft. Guess not = (alternative, in this context) pfft. if you say so
  
• Promise me you'll put it to good use = (roughly) make sure its useful / don't neglect using it / them
  
• Errant knight in shining, high-impact, reactive armor = brave knight in shining, shock-absorbing, reactive armor
  
• Given us reason to suspect that = (alternative) we're guessing this means that
  
• Of course you owe US nothing = (roughly) we can't force you to do this/ force you to do anything
  
• Wee bit rankled = a bit shaken
  
• Equip you with the proper armaments = (alternative, in this context) he'll make sure you're properly equipped / armed with weapons
  
• Pomp and circumstance fit for a hero's welcome upon your return = (roughly) when you return there will be a celebration worthy of a hero
  
• Not one for mincing words = I don't like being vague / unclear
  
• One of you lot from Anomalous Materials is man enough to finish this = (roughly) at least there's one person from the Anomalous Materials lab that has the balls to go through with this
  
• One final accoutrement = one final piece of equipment / wearable equipment tool
  
  - CHAPTER 19 - ENDGAME
  
• Quite a nasty piece of work you managed = (roughly) not exactly a small accomplishment / a rather large piece of work you did
  
• A battle you have no chance of winning = a battle impossible for you to win
  
• [Wipes Lapel, Audibly] = [Audibly wipes suit]
  
• No regrets, mr freeman = what is done, is done / thats what you decided / you can't change your mind now
  
  
  - SECURITY GUARD CHATTER
  
• 40 miles of rugged road = (literal) 60 kilometers of rough road (idiom intended meaning, I think...?) you look very messed up / it looks like you've been through a tough time
  
  - HECU CHATTER
  
• My dogs are barking = my feet ache
  
• I hate firewatch = I don't like guarding fire hazards
  
  - ACHIEVEMENTS
  
• Die in the AMS beam = (alternative) die in the testchamber's AMS beam
  
• Kill all Protozoans = (alternative) kill all the floating protozoans
  
• Cyanogen = poison gas
  
• Matter over mind = possesions above intellect, Over mind = hivemind
  
  - CHAPTER TITLES
  
• Black Mesa Inbound = (alternative) Arriving at- / Travelling to- Black Mesa (alternative) Black Mesa Train Ride
  
• "We've Got Hostiles!" = (alternative) enemies are incoming
  
• Power Up = (alternative) power increase (subtle meaning) aresenal / firepower power up
  
• "Forget About Freeman!" = (the qoute from the campaign) never mind Freeman / we no longer care about Freeman

When picking up the HEV suit in Chapter 2, the game tries to read bootup_english.txt.
In custom translations, as of Release 1.0, the initial header text appears like garbled text.
Make sure you named the language properly within the .txt file, or the game will crash when picking up the suit instead of displaying garbled text.

As user Red_Man has informed me in the comments of this guide, bootup text garble is related to how header text and non-header text is read and displayed by the game.

Header strings use a font that only supports Latin alphabet characters.
In addition, translating the non-header text causes both header and non-header text to get garbled.

There is no .txt file associated with some text used in multiplayer matches.

• % players
  
• Team Deathmatch / Deathmatch
  
• Spawn
  
• Top players on this server (!top10)
  
• # 1 % with % kills.
  
• - Number of recommended players
  
• - Map descriptions

There is no .txt file associated with that text. As of Release 1.0, it's hard-coded.

Missing letters in credits

Translated credits text might fail to correctly display some letters when reading from your custom credits_englsih.txt.

When putting special characters (non ascii) in 'CreditsTitle' text / big 'credits category' text, it causes that said category and all the ones loaded under it to have 'text garble' / unreadable text + missing letters.

ykalasnikov, who did the Turkish translation, fixed this by removing "ş" and "ı" from the credits_english.txt.
(The "ü" and "ç", didn't cause 'text garble' however, so it's a matter of trail and error to see what works.)

The 'CreditsNames' text / small 'people category' text, however could use "ş" and "ı" symbols without causing any 'text garble'.

When the script is done, or you're testing it out in game, you'll first need to check for closed qoutes.

Open up the subtitle file with notepad++, and choose a language that displays closed qoutes-formatting.

'Closed qoutes' = strings have a "-mark on both sides
It's easier to miss than you might think.

I find ESCRIPT to be very pleasant looking.
Example of a string missing closed qoutes.

• Go to ...\Black Mesa\bms and create a 'resource' folder
  
• Place the translated script file inside the 'resource' folder
  
• Open the CMD console (Right-click on windows-symbol)
  
• Copy this command into the console. (Replace %path to% with actual folder path)
  
  "...%path to%\Black Mesa\bin\captioncompiler.exe" closecaption_swedish.txt -game "...%path to%\Black Mesa\bms"
  
• Press enter... and... Voilá!
  
• Get the new .dat file and place it inside you project folder/resource
  

• Step 0: For mods like these you need a custom folder setup in bms.
  Click here for a guide on that.
  
  
• Step 1 a: Have the folder with the vpk.exe up, and drag the project folder onto it
  OR
  
  
• Step 1 b: Create a 'vpk.exe - shortcut' and have it above your project folder. Drag the folder onto it.
  - This option is very handy for if you compile your mod folder many times during testing.
  
• Step 2: Move the .vpk that was created into the custom folder.
  
• Step 3: Start Black Mesa and see if your text is loaded instead of the base-game/chosen one. (Usually _english.)

Uploading to the workshop

Find the ...\Black Mesa\bin folder, and open the blackmesa_publish.exe program.

The title, description and visibility can be changed from within Steam.
The thumbnail and content tags can only be modified in this program.

If you run this program again to update your mod with a different .vpk, make sure to have a backup of the desription you wrote for it on the workshop.
If your workshop page is long / includes fancy [url]-links and stuff its overwritten.
Not sure what causes it, but blackmesa_publish will always overwrite that stuff when an update is applied.
The publish tool has a 250 character limit, and it reapplies the text for your entry if it is ever updated (with "apply changes to UGC"), so make sure you have the workshop description backed up somewhere. (And if your title is also over 250 characters long, back that one up as well.)

It's recommended that your thumbnail is informative and effectively conveys the mod content together with the thumbnail.

For this tutorial I made this example:


If you have trouble with publishing the thumbnail through blackmesa_publish.exe, make sure the image is a 512x512 PNG-file.

When its uploaded, you can access the mod through the workshop to further tinker with its info, related images, people that helped you, etc. ;-)

Congratulations!
You've now written your very own fan-translation for Black Mesa!

Big thanks to the Black Mesa Discord![discord.gg]
If I hadn't talked to the folks over there, I wouldn't have known about or have done half of this stuff.

• English
  
• Spanish
  
• French
  
• Finnish
  
• German
  
• Italian
  
• Norwegian
  
• Portuguese
  
• Russian
  
• Ukrainian

• Russian from Red_Man, and others
  
• Swedish from MagicMaster667
  
• Vietnamese from zipzipfather
  
• Korean from KevinJRattman
  
• French from MerrickSimms, and others
  
• Italian from alfxItaly
  
• Simplified Chinese from ibox666, and others
  
• Traditional Chinese from srx910142, and others
  
• Turkish from ykalasnikov, and others
  
• Polish from Eselter
  
• Latin American Spanish from Trixon, and others