Do you think IIT Guwahati certified course can help you in your career?
Introduction
When we start translating a programming language doc, we face a problem: how to keep the original code as it is? Well, the play framework brings us a solution.
There is a markdown component in the doc that the play framework can translate. We are supposed to keep the original code samples the same as they were in the English doc. The “translators” usually maintain the translation quality. Here, the code samples are maintained as part of the core Play project, whereas the translated descriptions must be maintained manually.
This article will discuss the use of “translators” in translating the play doc. We will start our discussion by setting up a translator. Then we will discuss how to translate any doc. Afterward, we will see how to deal with code samples present in the doc. Then we will validate the doc and generate the translation report. At the end of the article, we will deploy our doc to the website, and then we will specify the doc version. Hence completing our discussion of translating the play documentation.
So let’s get started!
Prerequisites
Before starting our discussion of translating the play documentation. It is necessary to have sbt installed. It will also be helpful to have a clone of the Play repo with the branch you're translating checked out, so you have something to copy, to begin with.
If you're translating an unreleased version (i.e., a version created by you) of the Play doc. You'll need to build and publish that Play version locally on your machine. This can be done by:
sbt publishLocal
in the Play project's framework directory.
Setting up a Translator
We will start our discussion of translating the play documentation by setting up the translator. To do so, make a new sbt project with the structure shown below:
Finally, the Play doc plugin should be enabled in build.sbt, i.e.:
lazy val root = (project in file(".")).enablePlugins(PlayDocsPlugin)
You are now ready to begin translating!
Translating the Play Documentation
Start the doc server to start translating the play documentation by a translator. The documentation server will serve up your doc. You can see how it looks as you go.
$ sbt run
[info] Set current project to root (in build file:/Users/jroper/tmp/foo-translation/)
[info] play - Application started (Dev)
[info] play - Listening for HTTP on /0:0:0:0:0:0:0:0:9000
Doc server started, you can now view the docs by going to http://0:0:0:0:0:0:0:0:9000
In your project, have a markdown page from the Play repo. The directory structure in your project must match the directory structure in Play. This will ensure that the code samples work.
For example, if you choose to begin with manual/scalaGuide/main/http/ScalaActions.md, you must ensure that it is in your project's manual/scalaGuide/main/http/ScalaActions.md.
Translators and the Code Samples
While translating the play documentation, it is inevitable to avoid code. The Play doc is dense with code samples. They are mainly outside the markdown doc in compiled and tested source files.
Using the following syntax, these files are included in the doc:
@[label](code/path/to/SourceFile.java)
In general, you should leave these snippets alone in your translation. It will ensure that the code snippets in your translation are up to date with Play.
Overriding them may make sense in some cases. You can do this by directly including the code in the doc. You can also use a fenced block or extract it into your project's compiled code samples. If you do this, look at the Play doc sbt build files to see how you can configure sbt to assemble them.
Validating Documentation
The Play docs sbt plugin includes a doc validation task. Which do some basic tests on the doc. It is to ensure the accuracy of links and code sample references. You can test it by typing:
sbt validateDocs
You can also validate external site links in Play's doc. It is a separate task. As it depends on the websites with which the Play doc is linked. The validation task triggers DDoS filters on some websites. You can do it by running it as follows:
sbt validateExternalLinks
Translation Report
After translating the play documentation, it is good to generate the translation report. It is another helpful tool provided by Play. It shows which files have not been translated. It also attempts to detect issues, such as if the translation introduces new files or if code samples are missing.
This is especially useful when translating a new version of the doc. The addition or removal of code samples is a good indicator of change.
To view the translation report, start the doc server as usual. Then navigate to http://localhost:9000/@report in your browser. If the report was generated, it would serve a cached version by default. You can rerun the report by clicking the rerun report link.
Deploying Documentation to Playframework.com
Now after translating the play documentation. We are supposed to launch it on playframework.com. The doc on playframework.com is served from the git repo. If you want your translation to be served from the website. Put it in a GitHub repo and contact the Play team. They will add it to the website.
The git repo must be in a precise format. The current main branch is for the most recent Play development version. The Play doc for regular versions must be in branches like 2.3.x. Doc specific to a specific release of Play, for example, 2.3.1, will be served from a tag of the repo with that name.
After the Play team has configured playframework.com to serve your translation. Any changes pushed to your GitHub repo will be picked up within 10 minutes. It is because playframework.com performs a git fetch on all repo it uses once every 10 min.
Specifying the Documentation Version
By default, the play-docs-sbt-plugin uses the same version of the Play doc code samples and fallback markdown files as itself. So if you use 2.4.0 in plugins.sbt, you will get 2.4.0 of the doc code samples when you run the doc. This version can be controlled by modifying PlayDocsKeys.docsVersion in build.sbt:
PlayDocsKeys.docsVersion := "2.3.1"
This is mainly useful if you want to provide doc for Play versions. Before the play-docs-sbt-plugin, as far back as 2.2.0. The documentation for 2.1.x and earlier was not packaged and published as a jar file. The tooling will not work for those older versions.
Frequently Asked Questions
What is the use of the Play framework?
Scala & Java developers use the play framework. They can create web applications quickly and easily with Play Framework. Play's architecture is lightweight, stateless, and suitable for the web. The play is based on Akka. It helps us in having highly scalable and low resource-consuming applications.
Which architecture is used in the play framework?
Model-view-controller (MVC) architecture is used by the Play Framework. It was created in Scala. And it is also compatible with Java and other programming languages that are compiled by JVM bytecode.
How does the Play Framework define MVC?
A play application follows the MVC architectural pattern. For the Web architecture, the pattern splits the application into separate layers. These are the Presentation layer and the Model layer.
Conclusion
In this article, we briefly discussed translating the play documentation. We started by setting up a translator. Then we got to know how to translate doc. Afterward, we saw how to deal with code samples present in the doc. And then how to validate the doc. And generated the translation report.
At the end of the article, we deployed the doc to the website. And then specify the doc version. This concludes our discussion of translating the play documentation.
But suppose you have just started your learning process. And you are looking for questions from tech giants like Amazon, Microsoft, Uber, etc. In that case, you must look at the problems, interview experiences, and interview bundle for placement preparations.
Nevertheless, you may consider our paid courses to give your career an edge over others!
249+ registered 
