Software frameworks are great because they apply the principle of Separation of Concerns. A framework’s tools and code handle a specific need in a standard way for developers to write other code more easily. For example:
Web frameworks support receiving requests and sending responses.
Test frameworks include test case structure, runners, and reporting mechanisms.
Logging frameworks control how messages are gathered and stored.
Dependency injection frameworks create and manage object instances.
Recently, a question hit me: How far should a framework go to separate concerns? Should a framework try to do everything all-in-one, or should it behave more like a library that focuses on doing one thing well?
Let’s look at Python Web frameworks as an example. Django, the “Web framework for perfectionists with deadlines,” provides everything a developer could want out of the box. Flask, on the other hand, is a “microframework” that prides itself on minimalism: any extras must be handled by extensions or other packages. The differences between the two become clear when comparing some of their features:
Feature
Django
Flask
HTTP Requests and Routing
Included
Werkzeug (bundled)
Templates
Included
Jinja2 (bundled)
Forms
Included
None (Flask-WTF)
Object-Relational Mapping (ORM)
Included
None (SQLAlchemy)
Security
Included
None (Flask-Security)
Localization
Included
None (Flask-Babel)
Admin Interface
Included
None
Clearly, Django is all-in-one, while Flask is piece-by-piece. To make a serious Flask app, developers must pull in many extra pieces. There are many other frameworks with similar competitions:
JavaScript testing: Jasmine vs. Mocha
JavaScript development: Angular vs. React
Java BDD testing: Serenity vs. Cucumber-JVM
I think each approach has its merits. All-in-one frameworks are more convenient to use, especially for beginners. For developers who are new to a domain or just need to get something up fast, all-in-ones are the better choice. They come with all units already integrated together, and they often have good documentation. However, developing an all-in-one framework takes much more work because it covers multiple concerns. Developers may also feel shoehorned into the framework’s way of doing things. All-in-ones typically dictate what they believe to be the “best” solution.
Piece-by-piece frameworks require more expertise but offer greater flexibility. Developers can pick and choose the pieces they need, and they can change the packages used by the solution more easily. Found a better ORM? Not a problem. Need to localize the site in Chinese? Add it! Solutions can avoid excess weight and stay nimble for the future. The big challenge is successful integration. Furthermore, a library or framework for a singular concern tends to solve the concern in better ways simply because project contributors give it exclusive focus. The more I learn about a space, the more I lean towards a piece-by-piece approach.
As always, pick frameworks based on the needs at hand. For example, I like to use Django to make websites for my wife’s small businesses because the admin interface is just so convenient for her, even though I could get away with Flask. However, I’ll probably pick Mocha (piece-by-piece) over Jasmine (all-in-one) whenever I return to JavaScript testing.
The Python community, like many groups, has its own language – and I don’t mean just Python. There are many words and phrases thrown around that may confuse people new to Python. I originally shared some terms in my article, Which Version of Python Should I Use?, but below are some more of those colloquialisms for quick reference:
Git is one of the most popular version control systems (VCS) available, especially thanks to hosting vendors like GitHub. It keeps code safe and shareable. Sometimes, however, certain files should not be shared, like local settings or temporary configs. Git provides a few ways to make sure those files are ignored.
.gitignore
The easiest and most common way to ignore files is to use a gitignore file. Simply create a file named .gitignore in the repository’s root directory. Then, add names and patterns for any files and directories that should not be added to the repository. Use the asterisk (“*”) as a wildcard. For example, “*.class” will ignore all files that have the “.class” extension. Remember to add the .gitignore file to the repository so that it can be shared. As a bonus, Git hosting vendors like GitHub usually provide standard .gitignore templates for popular languages.
Any files covered by the .gitignore file will not be added to the repository. This approach is ideal for local IDE settings like .idea or .vscode, compiler output files like *.class or *.pyc, and test reports. For example, here’s GitHub’s .gitignore template for Java:
.git/info/exclude
As a best practice, .gitignore should be committed to the repository, which means all team members will share the same set of ignored files. However, some files should be ignored locally and not globally. Those files could be added to .gitignore, but large .gitignore files become cryptic and more likely to break other people’s setup. Thankfully, git provides a local-only solution: the .git/info/exclude file (under the repository’s hidden .git directory). Simply open it with a text editor and add new entries using the same file pattern format as .gitignore.
# Append a new file to ignore locally
echo "my_private_file" >> .git/info/exclude
skip-worktree
A .gitignore file prevents a file from being added to a repository, but what about preventing changes from being committed to an existing file? For example, developers may want to safely override settings in a shared config file for local testing. That’s where skip-worktree comes in: it allows a developer to “skip” any local changes made to a given file. Changes will not appear under “git status” and thus will not be committed.
Use the following commands:
# Ignore local changes to an existing file
git update-index --skip-worktree path/to/file
# Stop ignoring local changes
git update-index --no-skip-worktree path/to/file
Warning: The skip-worktree setting applies only to the local repository. It is not applied globally! Each developer will need to run the skip-worktree command in their local repository.
assume-unchanged
Another option for ignoring files is assume-unchanged. Like skip-worktree, it makes Git ignore changes to files. However, whereas skip-worktree assumes that the user intends to change the file, assume-unchanged assumes that the user will not change the file. The intention is different. Large projects using slow file systems may gain significant performance optimizations by marking unused directories as assume-unchanged. This option also works with other update-index options like really-refresh.
Use the following commands:
# Assume a file will be unchanged
git update-index --assume-unchanged path/to/file
# Undo that assumption
git update-index --no-assume-unchanged path/to/file
Again, this setting applies only to the local repository – it is not applied globally.
Comparison Table
Which is the best way to ignore files?
Method
Description
Best Use Cases
Scope
.gitignore file
Prevents files from being added to the repository.
Local settings, compiler output, test results, etc.
Global
.git/info/exclude file
Prevents local files from being added to the repository.
Local settings, compiler output, test results, etc.
Local
skip-worktree setting
Prevents local changes from being committed to an existing file.
Shared files that will have local overwrites, like config files.
Local
assume-unchanged setting
Allows Git to skip files that won’t be changed for performance optimization.
NuGet is a package manager for Microsoft .NET. It installs packages and manages dependencies for .NET projects. It is like Maven (Java) or pip (Python). The NuGet Gallery hosts thousands of popular packages like Json.NET, NUnit, and jQuery. If you develop .NET applications (like in C#), then you probably need to use NuGet.
Installing Packages
The easiest way to use NuGet is through Visual Studio, which includes NuGet features by default. Packages are managed per project. Right-click on a project in Solution Explorer and select “Manage NuGet Packages…” to open the project’s package manager page.
The Browse tab lets you search and install new packages.
The Installed tab shows which packages are installed and can uninstall them.
The Updates tab lets you update packages to their latest versions.
The NuGet Package Manager page for a project in Visual Studio
When packages are installed and updated, NuGet also pulls any dependencies they require. Visual Studio also creates a packages.config file for all dependencies. Then, just build and run!
NuGet Configuration
NuGet can be configured using a NuGet.Config file. This file can be placed under a project directory, a solution directory, or a system-wide location. One of the most common settings is the package sources: NuGet uses the public nuget.org repository by default, but others (like private company repos) can also be added. Check the nuget.config reference online for docs on all options. (Package sources can also be configured through Visual Studio under Tools > NuGet Package Manager > Package Manager Settings.)
NuGet Package Manager Console
Sometimes, it’s helpful to control NuGet directly through the Package Manager Console. From the menu bar: Tools > NuGet Package Manager > Package Manager Console. For example, when packages get messed up, I’ll run “Update-Package -Reinstall” to reinstall everything. (Right-clicking the solution and selecting “Restore NuGet Packages” never seems to work for me.) Check the help command or the official guide for more info.
The NuGet Package Manager Console in Visual Studio
NuGet CLI
The NuGet CLInuget.exe provides the full extent of NuGet features, including the ability to make packages. It is more powerful than the Package Manager Console. It must be installed independently – it does not come with Visual Studio. Check the NuGet CLI reference online for full details. The .NET Core CLIdotnet.exe can also be used for managing packages. See the feature comparison for the differences.
The NuGet CLI
Creating a NuGet Package
A NuGet package is basically a ZIP file with a .nupkg extension. It typically contains an assembly DLL and maybe other related files. Creating a NuGet package is pretty easy:
Install the NuGet CLI.
Create a .nuspec file for the project.
Add appropriate settings to the .nuspec file.
Run the “nuget pack” command to create the .nupkg file.
Publish the .nupkg file to the desired destination.
The .nuspec file can be created by running the “nuget spec” command in the project’s directory. The generated <project-name>.nuspec file will contain replacement tokens that will be substituted with values from the project’s AssemblyInfo when the package is built. Make sure to set AssemblyInfo values appropriately for the substitution. The version is especially important, and the automatic version format may be useful for guaranteeing uniqueness. Be sure to add any packages upon which the project depends as dependencies, too. (The .nuspec file can also be created manually.) Refer to the .nuspec reference for full details.
The standard package creation command is “nuget pack <project-name>.nuspec”. However, if the .nuspec file contains replacement tokens, then use “nuget pack <project-name>.csproj” instead. Once the package is created, it can be published publicly to nuget.org or to a private NuGet feed.
Below is an example .nuspec file with replacement tokens:
There were tons of great talks at PyCon 2018 – more than I could attend in person – that are now available on the PyCon 2018 YouTube channel. This post has links to my favorites. Enjoy!
By the Numbers: Python Community Trends in 2017/2018 (Dmitry Filippov, Ewa Jodlowska) – At the end of 2017, the Python Software Foundation teamed up with JetBrains to conduct an official Python Developers Survey. Data science is taking Python by storm, and Python 3 now has majority adoption. There are tons of other cool statistics, too!
How Netflix does failovers in 7 minutes flat (Amjith Ramanujam) – That speed at that scale is mind-blowing. This is a fascinating talk, even for non-engineers!
Solve Your Problem With Sloppy Python (Larry Hastings) – “If you ever start writing a shell script, delete it and write a Python script instead.” This talk is a jovial reminder that Python is a powerful tool, even for hack-n-slash jobs.
The AST and Me (Emily Morehouse-Valcarcel) – Emily gives a great overview of the inner workings of the Python language. This talk is a must-see for anyone into compiler theory.
Dataclasses: The code generator to end all code generators (Raymond Hettinger) – Dataclasses are new data structures to Python to generate classes based on specs.
Pipenv: the Future of Python Dependency Management (Kenneth Reitz) – Pipenv is a new tool that makes pip, Pipfile, and virtualenv easier to use together. Kenneth gives a good overview of Python packaging and why pipenv is awesome.
Type-checked Python in the real world (Carl Meyer) – Sometimes, I wish Python had static typing. Now, it can! Facebook has done some innovative things to make it possible.
Beyond Unit Tests: Taking Your Testing to the Next Level (Hillel Wayne) – Property tests + contracts = integration tests. Hillel gives a fantastic strategy for making tests smarter.
“WHAT IS THIS MESS?” – Writing tests for pre-existing code bases (Justin Crown) – This is a pragmatic guide to adding new tests to old code. Now, you’ll never procrastinate on your tests again!
Demystifying the Patch Function (Lisa Roach) – Mocking is a great practice for limiting scope in unit tests. Whether using unittest.mock or other patching/mocking packages, this is a great talk for learning why and how to do mocking in unit tests!
Automating Code Quality (Kyle Knapp) – One of Python’s most beloved traits is its elegance. Maintaining high standards of code quality can be challenging for large projects, though. Kyle shows how to use existing tools to drive higher quality.
Keynote (Ying Li) – [35:07] – Ying is a software security engineer at Docker. In her keynote, she urged all people involved in technology to learn the basics of security. Definitely watch the video recording – she used a fun story to illustrate her points.
Keynote: The People and Python (Qumisha Goss) – [1:07:35] – “Q” is a librarian at the Detroit Public Library who taught herself Python so she could teach coding classes to kids. She shared the highs and lows of her experiences, especially in light of many disadvantages her students had. My favorite takeaway was to “cultivate greatness in others.”
The main reason I went to PyCon 2018 was to deliver a talk entitled “Behavior-Driven Python” about behave, one of Python’s most popular BDD test automation frameworks. One of my major professional goals for 2018 was to speak at a conference – and any conference would do. Fortunately for me, PyCon accepted my proposal, and Piper Companies in Raleigh graciously footed the bill! The video recording for my talk is linked below. It also has a GitHub example project and a companion article. (I’ll write a separate article with links to other talks I enjoyed.)
The Destination
PyCon 2018 was held in Cleveland, Ohio. I had never been to Cleveland before, and I found the downtown area to be charming. Everything I needed was within walking distance: the Huntington Convention Center where the conference was held, the DoubleTree by Hilton on Lakeside Ave where I stayed, the skyline, the city hall, the Rock and Roll Hall of Fame, the Great Lakes Science Center, and Lake Erie itself.
Interesting shot on a bridge near the Rock and Roll Hall of Fame.
“FREE” stamp sculpture next to city hall.
The Huntington Convention Center, where PyCon 2018 took place.
Cleveland has a nice skyline.
I flew into Cleveland on the evening of Thursday, May 10. Unfortunately, I missed the opening reception because my Frontier Airlines flight was delayed. (I guess I got what I paid for.) When I arrived, I had only one destination in mind: Great Lakes Brewing Company. Great Lakes has been one of my favorite breweries since I first started drinking craft beer in college. I boarded the Red Line train at the airport and rode it directly to the Ohio City station, where their pub is located. The food and beer did not disappoint!
The Red Line
Great Lakes Brewing Company
Great Lakes Brewing Company
GLBC Brats and Pierogies
Ohio City
GLBC Flight Set
Delayed flights are never fun.
The First Morning
PyCon 2018 had three major phases: tutorials from May 9-10, talks and events from May 11-13, and sprints from May 14-17. I attended only from May 11-13 for the “main” part of the conference. I really didn’t know what to expect, but I was blown away by what I found.
The first thing I did on the first day was registration. I showed up at about 8am to get my badge and my conference t-shirt. The volunteers also handed me a “swag bag,” pre-populated with a map and some random goodies. Since I had my backpack, I didn’t think I would need an extra bag – boy, was I wrong!
The main conference area was an expo hall full of companies and organizations giving away endless freebies, much to my naive surprise. (This was nothing like the last conference I attended, PyData Carolinas 2016.) The major stalls were Microsoft, Amazon (AWS), Google, Facebook/Instagram, LinkedIn, Anaconda, O’Reilly, and Heroku. Others included the Python Software Foundation, Django Girls, JetBrains, Elasticsearch, ChowNow, Yelp, Patreon, Squarespace, Linode, platform.sh, PostgreSQL, Nylas, DigitalOcean, DataDog, Cactus, Six Feet Up, OfferUp, Twilio, Nexmo, Okta, Pluralsight, Zapier, Bloomberg, Shopify, PyBee, EdgeDB, Anvil, and others I can’t remember. Over the three days of main events, I talked with people at nearly every stall to learn about what they do and to score that dank swag. I walked away with twelve t-shirts, five pairs of socks, laminated Python guides, a JetBrains yo-yo, a Google puzzle, Yelp gloves, a Facebook earbuds case, an OfferUp water bottle, a couple koozies, and a countless number of stickers.
The Django Pony at the Django Girls table!
The welcome banner at my hotel
All the swag!
The talks in Grand Ballroom A. Mine was Friday at 12:10pm!
Setting up the expo hall
The expo hall entrance
While waiting for the first keynote address, I ran into Kenneth Reitz at the Python Software Foundation table. Kenneth is the original author of requests and pipenv. It was a pleasure to meet him in person. He also interviewed me for his PyCon 2018 podcast! My segment is at 19:11.
I was about to go to the keynote address when I walked by the O’Reilly stall and discovered a book signing: Harry J.W. Percival was scheduled to give away free signed copies of the second edition of his book, Test-Driven Development with Python. I got my “golden ticket,” waited in line, skipped the keynote, and scored that dankest swag of the conference. O’Reilly was giving out other books throughout the conference, but as a Software Engineer in Test, this one was the big kahuna for me. #worthit
Kenneth Reitz (left) and the Automation Panda (right)
The O’Reilly book signing
My talk, “Behavior-Driven Python,” was scheduled at 12:10pm in Grand Ballroom A. I wasn’t terribly nervous because I had given this sort of talk many times, but I was worried that I would run out of time. Before speakers give their talks, they go to the “green room” where they test projector cables and meet the “runner” who will take them to the auditorium. I got to meet other speakers, which made me feel more comfortable. My talk got off to a delayed start due to some technical difficulties with the projector, but I think it went really well. The ballrooms could each seat several hundred people, and it looked like my talk was fairly well attended. A number of people asked me questions afterwards. Then, I ended up having lunch with a new friend I met named Gabriel, too!
The Rest of Day 1
I spent the rest of the afternoon attending talks, which can be mentally exhausting after too much. However, at the end of the day, I got to spend some sweet time with my dear friend Kennedy from college. Kennedy reached out to me before the conference to let me know that he would be there. I ran into him each day, but we got to spend the most time together sitting outside Ballroom A just catching up on life. We hadn’t seen each other since 2010 at RIT. Kennedy is really getting into software infrastructure and DevOps-like work. It was such a blessing to see him there.
My bro Kennedy sports that Linode shirt like a boss!
Dinner was another fortuitous blessing. ChowNow invited me to dinner and drinks at TownHall. I met their chief product officer, their engineers, and their recruiters. We talked a lot about test automation. They’re in a very similar situation as my current company, PrecisionLender: a hundred people and growing, realizing their need for automated feature tests, and discovering how hard it is to build an automation solution themselves or find someone who can. They were really great people doing awesome things, and I can’t wait to see them grow.
ChowNow also had a fun giveaway challenge. To enter, one needed to hit a REST API endpoint, which then returned further instructions. It was a bit of a puzzle – I got confused for the first few minutes, but after a hearty facepalm I figured out the challenge and successfully submitted my entry. (Python REPL and requests FTW!) The grand prize was an iPad Pro, but I won the consolation prize of $20 in ChowNow bucks. Not bad.
The Second Day
For me, Day 2 at PyCon was almost entirely about talks. The morning keynotes were really inspiring: Ying Li told a great story modeled after the Wizard of Oz about how everyone plays a part in security, and Qumisha Goss shared how she inspires kids at the Detroit public library to get into coding with Python. There were more talks I wanted to attend than I could. I learned about sloppy Python, developing arcade-style games, statistics on Python users, Appium, and compiler tools.
In the expo hall, my most memorable conversation was at the Python Bytes / Talk Python To Me table. These are major Python podcasts. Julian Sequeira of PyBites told me all about the #100DaysOfCode in Python, which I really want to try so I can learn about things beyond my domain. He then introduced me to Brian Okken, who wrote Python Testing with pytest and runs the Test and Code podcast. We talked quite a bit about testing practices and frameworks. I almost convinced him of BDD’s benefits, and he tried to convince me that unit testing is waste. It was a great conversation, and I really want to learn more about Brian’s pragmatic testing perspective.
Julian championing the Sceptre of Python!
That evening, Instagram invited me to dinner. I thought it would be drinks and appetizers at a bar, like with ChowNow. Oh, no, it was … Let me tell the story. Before PyCon started, Instagram invited me to join them for a special dinner. I think they invited me because I was a speaker. Instagram provided promo codes for a free Lyft to Crop Bistro, one of the best restaurants in the city. It resides in an old bank: marble columns and fresco paintings on the walls. When I arrived, the hostess walked me to the back, down the stairs, through the kitchen, and into the bank’s old vault, which had been converted into a private party room. They served a full three-course meal with a full bar, and it was damn good. That ribeye steak… I met a lot of great people, too. I talked with Instagram’s release manager at length about struggles with test automation. I also got to chat with a number of their engineers (many of whom were from China), as well as other Pythonistas who were invited. It was a wonderful event, and I truly thank Instagram for the invitation.
Instagram Cookie
Crop Bistro
The Vault at Crop Bistro
A 3-Course Meal!
Also, I want to say that the weather in Cleveland was pretty darn cold! Daily temperatures were in the 50s, while at the same time in Raleigh, they were in the 90s. I froze my ears off walking from the hotel to the convention center!
The Third Day
At the Instagram dinner, I met a few guys who help organize Python conferences. They encouraged me to submit proposals to PyGotham and PyOhio. So, when I woke up on Day 3, I did! Hopefully, my proposals will be accepted.
Representing PrecisionLender! Someone asked me about the four values on the back of the shirt.
The Job Fair
The main event in the morning was the Poster expo / Job Fair. However, since I had already met most of the companies, I spent most of my time at the Rock and Roll Hall of Fame instead. I’m a huge fan of rock music. The museum had awesome exhibits with really cool memorabilia. I even got to vote for new inductees – I voted for Iron Maiden! I headed back to PyCon for the afternoon talks, but then I skipped out of the finale to finish seeing all of the Rock and Roll Hall of Fame exhibits before the museum closed.
Cliff Burton’s Bass Guitar (Metallica)
Outside the Rock and Roll Hall of Fame
The Beatles entry in the Hall of Fame
Angus Young’s Stage Outfit
Chinese Lunch
Aerosmith’s Set
My original dinner plan was to visit another local brewery. PyCon was hosting an event dinner at the Great Lakes Science Center, but I didn’t register in time to get a ticket. Nevertheless, my friend Kennedy offered me his meal ticket since he was returning home that afternoon. Hashtag-BLESSED. The museum was so cool. My favorite part was the NASA Glenn Visitor Center – they had one of the Apollo Skylab capsules! Many of us Pythonistas built a really tall tower out of wood blocks that we had to knock down once dinner was ready. The food was excellent, too: steak, salmon, mac ‘n cheese, green beans, and cheesecake for dessert.
Delicious Dinner
Block Tower!
Mercury Capsule
Apollo Capsule from Skylab
Inside the Mercury Capsule
Apollo Capsule from Skylab
My (Delta) direct flight home left on time Monday morning. I could barely fit all the swag into my suitcase! I caught a cold while attending the conference, but thankfully it didn’t take effect until I was back home.
Major Takeaways
So much happened at PyCon 2018. Even though I was doing stuff nonstop for three days, there was still so much more there to do. It will take me a few weeks to fully process everything. Here were my major takeaways:
I accomplished my goals. Before going to PyCon, I set three major goals for myself: (1) get a pulse on the state and direction of Python, (2) establish rapport in the community, and (3) become inspired to pursue greater work. CHECK! I met a lot of great people who all love using Python. A number of people really enjoyed my talk. I learned how so many groups, from top-tier Silicon Valley companies to local user orgs, are using Python to do cool stuff. There are also now just as many data scientists as web developers using Python. Seeing Python used in so many different domains really inspired me to learn more about those domains in which my knowledge is limited. I feel like I have more work to do after the conference than I did to prepare for it!
The Python community is so welcoming and friendly. When PyCon’s banner says, “For the community, by the community,” it’s true. This conference was about people much more than it was about programming. I was initially afraid that I would be lonely because I didn’t know anyone, but once I got there, everyone was outgoing; even me! Python is a language for everyone from beginners to experts, and there was no sense of elitism whatsoever at the conference. The atmosphere reminded me very much of freshman orientation week at RIT, when total strangers would strike up conversations and bestow well-wishes at every turn.
All companies have major test automation struggles. There is a universal awareness of the need for good testing, but there is also universal struggle to develop reliable feature tests at scale. Knowing that companies like Facebook/Instagram and ChowNow have problems similar to companies where I have worked gives me boosted motivation as a Software Engineer in Test to keep going!
Never write shell scripts. Just write Python scripts. Yes! This came from the “sloppy Python” talk. It’s so true. Shell scripting is so low-level and often unreadable. Plus, Python is cross-platform!
Flask is a big deal. Flask is a minimalist Pythonic web framework. It is a lightweight alternative to Django and Pyramid. Everyone was talking about it. O’Reilly was giving away books about it.
Prep for PyCon 2019! I want to return to PyCon very much. Next year, I have a better understanding of the talks, so I can make better proposals. I’ll also check out the open spaces and lightning talks. PyCon 2019 will be back in Cleveland, too!
What’s Next?
I feel like I have so much more to learn! Here’s what’s next for me:
Watch videos for all the talks I missed.
Come up with a personal professional development plan.
Django is a fantastic Python Web framework, and one of its great out-of-the-box features is internationalization (or “i18n” for short). It’s pretty easy to add translations to nearly any string in a Django app, but what about translating admin site pages? Titles, names, and actions all need translations. Those admin pages are automatically generated, so how can their words be translated? This guide shows you how to do it easily.
Want an internationalized admin site like this? Follow this guide to find out how!
i18n Review
If you are new to translations in Django, definitely read the official Translation page first. In a nutshell, all strings that need translation should be passed into a translation function for Python code or a translation block for Django template code. Django management commands then generate language-specific message files, in which translators provide translations for the marked strings, and finally compile them for app use. Note that translations require the gettext tools to be installed on your machine. Django also provides some advanced logic for handling special cases like date formats and pluralization, too. It’s really that simple!
Initial Setup
A Django project needs some basic config before doing translations, which is needed for both the main site and the admin.
Enabling Internationalization
Make sure the following settings are given in settings.py:
# settings.py
LANGUAGE_CODE = 'en-us' # or other appropriate code
USE_I18N = True
USE_L10N = True
They were probably added by default. The Booleans could be set to False to give apps with no internationalization a small performance boost, but we need them to be True so that translations happen.
Changing Locale Paths
By default, message files will be generated into locale directories for each app with strings marked for translation. You may optionally want to set LOCALE_PATHS to change the paths. For example, it may be easiest to put all message files into one directory like this, rather than splitting them out by app:
This will avoid translation duplication between apps. It’s a good strategy for small projects, but be warned that it won’t scale well for larger projects.
Middleware for Automatic Translation
Django provides LocaleMiddleware to automatically translate pages using “context clues” like URL language prefixes, session values, and cookies. (The full pecking order is documented under How Django discovers language preference on the official doc page.) So, if a user accesses the site from China, then they should automatically receive Chinese translations! To use the middleware, add django.middleware.locale.LocaleMiddleware to the MIDDLEWARE setting in settings.py. Make sure it comes after SessionMiddleware and CacheMiddleware and before CommonMiddleware, if those other middlewares are used.
Getting automatic translations from context clues is great, but it’s nevertheless useful to have direct URLs to different page translations. The i18n_patterns function can easily add the language code as a prefix to URL patterns. It can be applied to all URLs for the site or only a subset of URLs (such as the admin site). Optionally, patterns can be set so that URLs without a language prefix will use the default language. The main caveat for using i18n_patterns is that it must be used from the root URLconf and not from included ones. The project’s root urls.py file should look like this:
# urls.py
from django.conf.urls.i18n import i18n_patterns
from django.contrib import admin
from django.urls import path
urlpatterns = i18n_patterns(
# ...
path('admin/', admin.site.urls),
# ...
# If no prefix is given, use the default language
prefix_default_language=False
)
Limiting Language Choices
When adding language prefixes to URLs, I strongly recommend limiting the available languages. Django includes ready-made message files for several languages. A site would look bad if, for example, the “/fr/” prefix were available without any French translations. Set the available languages using LANGUAGES in settings.py:
# settings.py
from django.utils.translation import gettext_lazy as _
LANGUAGES = [
('en', _('English')),
('zh-hans', _('Simplified Chinese')),
]
Note that language codes follow the ISO 639-1 standard.
Doing the Translations
With the configurations above, translations can now be added for the main site! The steps below show how to add translations specifically for the admin. Unless there is a specific need, use lazy translation for all cases.
Out-of-the-Box Phrases
Admin site pages are automatically generated using out-of-the-box templates with lots of canned phrases for things like “login,” “save,” and “delete.” How do those get translated? Thankfully, Django already has translations for many major languages. Check out the list under django/contrib/admin/locale for available languages. Django will automatically use translations for these languages in the admin site – there’s nothing else you need to do! If you need a language that’s not available, I strongly encourage you to contribute new translations to the Django project so that everyone can share them. (I suspect that you could also try to manually create messages files in your locale directory, but I have not tested that myself.)
Custom Admin Titles
There are a few ways to set custom admin site titles. My preferred method is to set them in the root urls.py file. Wherever they are set, mark them for lazy translation. It’s easy to overlook them!
from django.contrib import admin
from django.utils.translation import gettext_lazy as _
admin.site.index_title = _('My Index Title')
admin.site.site_header = _('My Site Administration')
admin.site.site_title = _('My Site Management')
App Names
App names are another set of phrases that can be easily missed. Add a verbose_name field with a translatable string to every AppConfig class in the project. Do not simply try to translate the string given for the name field: Django will yield a runtime exception!
from django.apps import AppConfig
from django.utils.translation import gettext_lazy as _
class CustomersConfig(AppConfig):
name = 'customers'
verbose_name = _('Customers')
Model Names
Models are full of strings that need translations. Here are the things to look for:
Give each field a verbose_name value, since the identifiers cannot be translated.
Mark help texts, choice descriptions, and validator messages as translatable.
Add a Meta class with verbose_name and verbose_name_plural values.
Look out for any other strings that might need translations.
Here is an example model:
from django.db import models
from django.core.validators import RegexValidator
from django.utils.translation import gettext_lazy as _
class Customer(models.Model):
name = models.CharField(
max_length=100,
help_text=_('First and last name.'),
verbose_name=_('name'))
address = models.CharField(
max_length=100,
verbose_name=_('address'))
phone = models.CharField(
max_length=10,
validators=[RegexValidator(
'^\d{10}$',
_('Phone must be exactly 10 digits.'))],
verbose_name=_('phone number'))
class Meta:
verbose_name = _('customer')
verbose_name_plural = _('customers')
Run the Commands
Once all strings are marked for translation, generate the message files:
# Generate message files for a desired language
python manage.py makemessages -l zh_Hans
# After adding translations to the .po files, compile the messages
python manage.py compilemessages
Warning: The language code and the locale name may be different! For example, take Simplified Chinese: the language code is “zh-hans”, but the locale name is “zh_Hans”. Notice the underscore and the caps. Locale names often include a country code to differentiate language nuances, like American English vs. British English. Refer to django/contrib/admin/local for a list of examples.
Bonus: Admin Language Buttons
With LocaleMiddleware and i18n_patterns, pages should be automatically translated based on context or URL prefix. However, it would still be great to let the user manually switch the language from the admin interface. Clicking a button is more intuitive than fumbling with URL prefixes.
There are many ways to add language switchers to the admin site. To me, the most sensible way is to add flag icons to the title bar. Behind the scenes, each flag icon would be linked to a language-prefixed URL for the page. That way, whenever a user clicks the flag, then the same page is loaded in the desired language.
It’s pretty easy to make something like this, but it needs a few steps.
Language Code Prefix Switcher
Since URL paths use i18n_patterns, their language codes can be trusted to be uniform. A utility function can easily add or substitute the desired language code as a URL path prefix. For example, it would convert “/admin/” and “/en/admin/” into “/zh-hans/admin/” for Simplified Chinese. This function should also validate that the path and language are correct. It can be put anywhere in the project. Below is the code:
from django.conf import settings
def switch_lang_code(path, language):
# Get the supported language codes
lang_codes = [c for (c, name) in settings.LANGUAGES]
# Validate the inputs
if path == '':
raise Exception('URL path for language switch is empty')
elif path[0] != '/':
raise Exception('URL path for language switch does not start with "/"')
elif language not in lang_codes:
raise Exception('%s is not a supported language code' % language)
# Split the parts of the path
parts = path.split('/')
# Add or substitute the new language prefix
if parts[1] in lang_codes:
parts[1] = language
else:
parts[0] = "/" + language
# Return the full new path
return '/'.join(parts)
Prefix Switch Template Filter
Ultimately, this function must be called by Django templates in order to provide links to language-specific pages. Thus, we need a custom template filter. The filter implementation module can be put into any app, but it must be in a sub-package named templatetags – that’s how Django knows to look for custom template tags and filters. The new filters will be easy to write because we already have the switch_lang_code function. (Separating the logic to handle the prefix from the filter itself makes both more testable and reusable.) The code is below:
# [app]/templatetags/i18n_switcher.py
from django import template
from django.template.defaultfilters import stringfilter
register = template.Library()
@register.filter
@stringfilter
def switch_i18n_prefix(path, language):
"""takes in a string path"""
return switch_lang_code(path, language)
@register.filter
def switch_i18n(request, language):
"""takes in a request object and gets the path from it"""
return switch_lang_code(request.get_full_path(), language)
Admin Template Override
Finally, admin templates must be overridden so that we can add new elements to the admin pages. Any admin template can be overridden by creating new templates of the same name under [project-root]/templates/admin. Parent content will be used unless explicitly overridden within the child template file. Since we want to change the title bar, create a new template file for base_site.html with the following contents:
The static CSS file named css/custom_admin.css should have the following contents:
Notice that the whole userlinks block had to be rewritten to fit the flag into place. The static image files for the flags are simply free flag emojis. They are hyperlinked to the appropriate language URL for the page: the switch_i18n filter is applied to the active request object to get the desired language-prefixed path. (Note: In my example code, I removed the “View Site” link because my site didn’t need it.)
Completed View
The admin site should now look like this:
This slideshow requires JavaScript.
The files in my project needed for the admin language buttons are organized like this (without showing other files in the project):
As mentioned before, flag icons in the title bar are simply one way to provide easy links to translated pages. It works well when there are only a few language choices available. A different view would be better for more languages, like a dropdown, a second line in the title bar, or even a page footer.
With a bit more polishing, this would also make a nifty little Django app package that others could use for their projects. Maybe I’ll get to that someday.
