===============
xblocks-contrib
===============
This repository is the new home for XBlocks, a core component of the Open edX ecosystem.
This project involves the extraction of XBlocks from the edx-platform.
Project Overview
=======================
XBlocks are modular components that enable rich interactive learning experiences in Open edX courses.
Historically, the XBlock code was tightly coupled with the edx-platform, making it challenging to manage and extend.
By extracting XBlocks into this dedicated repository, we can reduce the complexity of the edx-platform, making it more maintainable and scalable.
XBlocks Being Moved Here
************************
These are the XBlocks being moved here, and each of their statuses:
* ``poll_question`` -- Placeholder
* ``word_cloud`` -- Placeholder
* ``annotatable`` -- Placeholder
* ``lti`` -- Placeholder
* ``html`` -- Placeholder
* ``discussion`` -- Placeholder
* ``problem`` -- Placeholder
* ``video`` -- Placeholder
The possible XBlock statuses are:
* Placeholder: It's just a cookiecutter thumbs-up block.
* In Development: We're building and testing this block.
* Ready to Use: You can try this on your site using the Waffle flag.
* Done The built-in block has been removed. The setup.py entrypoint has been removed from edx-platform and added to xblock-contrib.
Developing a new XBlock
=======================
There's a handy script ``utils/create_xblock.sh`` that you can use to create XBlock here. just run ::
$ utils/create_xblock.sh
It will ask for XBlock name and XBlock class name that you want to use. Just enter these values and XBlock should be ready to work.
If faced with permission or access error run::
$ chmod +x utils/create_xblock.sh
and run it.
Testing with Docker
********************
This XBlock comes with a Docker test environment ready to build, based on the xblock-sdk workbench. To build and run it::
$ make dev.run
The XBlock SDK Workbench, including this XBlock, will be available on the list of XBlocks at http://localhost:8000
Translating
*************
Internationalization (i18n) is when a program is made aware of multiple languages.
Localization (l10n) is adapting a program to local language and cultural habits.
For information on how to enable translations, visit the `Open edX XBlock tutorial on Internationalization <https://docs.openedx.org/projects/xblock/en/latest/xblock-tutorial/edx_platform/edx_lms.html#internationalization-support>`_.
The included Makefile contains targets for extracting, compiling and validating translatable strings.
The general steps to provide multilingual messages for a Python program (or an XBlock) are:
1. Mark translatable strings.
2. Run i18n tools to create raw message catalogs.
3. Create language specific translations for each message in the catalogs.
4. Use ``gettext`` to translate strings.
5. Mark translatable strings
----------------------------
Mark translatable strings in python::
from django.utils.translation import ugettext as _
# Translators: This comment will appear in the `.po` file.
message = _("This will be marked.")
See `edx-developer-guide <https://docs.openedx.org/en/latest/developers/references/developer_guide/internationalization/i18n.html#python-source-code>`__
for more information.
You can also use ``gettext`` to mark strings in javascript::
// Translators: This comment will appear in the `.po` file.
var message = gettext("Custom message.");
See `edx-developer-guide <https://docs.openedx.org/en/latest/developers/references/developer_guide/internationalization/i18n.html#javascript-files>`__
for more information.
2. Run i18n tools to create Raw message catalogs
------------------------------------------------
After marking strings as translatable we have to create the raw message catalogs.
These catalogs are created in ``.po`` files. For more information see
`GNU PO file documentation <https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html>`_.
These catalogs can be created by running::
$ make extract_translations
This command will create the necessary ``.po`` files under
``xblocks-contrib/xblocks_contrib/<xblock name>/conf/locale/en/LC_MESSAGES/text.po``.
The ``text.po`` file is created from the ``django-partial.po`` file created by
``django-admin makemessages`` (`makemessages documentation <https://docs.djangoproject.com/en/5.1/topics/i18n/translation/#message-files>`_),
this is why you will not see a ``django-partial.po`` file.
You will need to have `edx-i18n-tools` that you can get by:
$ make requirements
3. Create language specific translations
----------------------------------------
3.1 Add translated strings
~~~~~~~~~~~~~~~~~~~~~~~~~~
After creating the raw message catalogs, all translations should be filled out by the translator.
One or more translators must edit the entries created in the message catalog, i.e. the ``.po`` file(s).
The format of each entry is as follows::
# translator-comments
A. extracted-comments
#: reference…
#, flag…
#| msgid previous-untranslated-string
msgid 'untranslated message'
msgstr 'mensaje traducido (translated message)'
For more information see
`GNU PO file documentation <https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html>`_.
To use translations from transifex use the follow Make target to pull translations::
$ make pull_translations
See `config instructions <https://github.com/openedx/i18n-tools#transifex-commands>`_ for information on how to set up your
transifex credentials.
See `transifex documentation <https://developers.transifex.com/docs/django-file-based>`_ for more details about integrating
django with transiflex.
3.2 Compile translations
~~~~~~~~~~~~~~~~~~~~~~~~
Once translations are in place, use the following Make target to compile the translation catalogs ``.po`` into
``.mo`` message files::
$ make compile_translations
The previous command will compile ``.po`` files using
``django-admin compilemessages`` (`compilemessages documentation <https://docs.djangoproject.com/en/5.1/topics/i18n/translation/#compiling-message-files>`_).
After compiling the ``.po`` file(s), ``django-statici18n`` is used to create language specific catalogs. See
``django-statici18n`` `documentation <https://django-statici18n.readthedocs.io/en/v2.5.0/>`_ for more information.
To upload translations to transiflex use the follow Make target::
$ make push_translations
See `config instructions <https://github.com/openedx/i18n-tools#transifex-commands>`_ for information on how to set up your
transifex credentials.
See `transifex documentation <https://developers.transifex.com/docs/django-file-based>`_ for more details about integrating
django with transiflex.
**Note:** The ``dev.run`` make target will automatically compile any translations.
**Note:** To check if the source translation files (``.po``) are up-to-date run::
$ make detect_changed_source_translations
4. Use ``gettext`` to translate strings
---------------------------------------
Django will automatically use ``gettext`` and the compiled translations to translate strings.
Troubleshooting
~~~~~~~~~~~~~~~
If there are any errors compiling ``.po`` files run the following command to validate your ``.po`` files::
$ make validate
See `django's i18n troubleshooting documentation
<https://docs.djangoproject.com/en/5.1/topics/i18n/translation/#troubleshooting-gettext-incorrectly-detects-python-format-in-strings-with-percent-signs>`_
for more information.
Change Log
##########
..
All enhancements and patches to xblocks-contrib will be documented
in this file. It adheres to the structure of https://keepachangelog.com/ ,
but in reStructuredText instead of Markdown (for ease of incorporation into
Sphinx documentation and the PyPI description).
This project adheres to Semantic Versioning (https://semver.org/).
.. There should always be an "Unreleased" section for changes pending release.
Unreleased
**********
*
0.1.0 – 2024-07-04
**********************************************
Added
=====
* First release on PyPI.
Raw data
{
"_id": null,
"home_page": "https://github.com/openedx/xblocks-contrib",
"name": "xblocks-contrib",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "Python edx",
"author": "Open edX Project",
"author_email": "oscm@openedx.org",
"download_url": "https://files.pythonhosted.org/packages/77/b9/751d48e25bd95636720b354bfdde61184cf0b583e8a5ffe5bc3e14eacd6b/xblocks_contrib-0.1.0.tar.gz",
"platform": null,
"description": "===============\nxblocks-contrib\n===============\n\nThis repository is the new home for XBlocks, a core component of the Open edX ecosystem.\nThis project involves the extraction of XBlocks from the edx-platform.\n\nProject Overview\n=======================\n\nXBlocks are modular components that enable rich interactive learning experiences in Open edX courses.\nHistorically, the XBlock code was tightly coupled with the edx-platform, making it challenging to manage and extend.\nBy extracting XBlocks into this dedicated repository, we can reduce the complexity of the edx-platform, making it more maintainable and scalable.\n\nXBlocks Being Moved Here\n************************\n\nThese are the XBlocks being moved here, and each of their statuses:\n\n* ``poll_question`` -- Placeholder\n* ``word_cloud`` -- Placeholder\n* ``annotatable`` -- Placeholder\n* ``lti`` -- Placeholder\n* ``html`` -- Placeholder\n* ``discussion`` -- Placeholder\n* ``problem`` -- Placeholder\n* ``video`` -- Placeholder\n\nThe possible XBlock statuses are:\n\n* Placeholder: It's just a cookiecutter thumbs-up block.\n* In Development: We're building and testing this block.\n* Ready to Use: You can try this on your site using the Waffle flag.\n* Done The built-in block has been removed. The setup.py entrypoint has been removed from edx-platform and added to xblock-contrib.\n\n\nDeveloping a new XBlock\n=======================\n\nThere's a handy script ``utils/create_xblock.sh`` that you can use to create XBlock here. just run ::\n\n $ utils/create_xblock.sh\n\nIt will ask for XBlock name and XBlock class name that you want to use. Just enter these values and XBlock should be ready to work.\n\nIf faced with permission or access error run::\n\n $ chmod +x utils/create_xblock.sh\n\nand run it.\n\nTesting with Docker\n********************\n\nThis XBlock comes with a Docker test environment ready to build, based on the xblock-sdk workbench. To build and run it::\n\n $ make dev.run\n\nThe XBlock SDK Workbench, including this XBlock, will be available on the list of XBlocks at http://localhost:8000\n\nTranslating\n*************\n\nInternationalization (i18n) is when a program is made aware of multiple languages.\nLocalization (l10n) is adapting a program to local language and cultural habits.\n\nFor information on how to enable translations, visit the `Open edX XBlock tutorial on Internationalization <https://docs.openedx.org/projects/xblock/en/latest/xblock-tutorial/edx_platform/edx_lms.html#internationalization-support>`_.\n\nThe included Makefile contains targets for extracting, compiling and validating translatable strings.\nThe general steps to provide multilingual messages for a Python program (or an XBlock) are:\n\n1. Mark translatable strings.\n2. Run i18n tools to create raw message catalogs.\n3. Create language specific translations for each message in the catalogs.\n4. Use ``gettext`` to translate strings.\n\n5. Mark translatable strings\n----------------------------\n\nMark translatable strings in python::\n\n from django.utils.translation import ugettext as _\n\n # Translators: This comment will appear in the `.po` file.\n message = _(\"This will be marked.\")\n\nSee `edx-developer-guide <https://docs.openedx.org/en/latest/developers/references/developer_guide/internationalization/i18n.html#python-source-code>`__\nfor more information.\n\nYou can also use ``gettext`` to mark strings in javascript::\n\n\n // Translators: This comment will appear in the `.po` file.\n var message = gettext(\"Custom message.\");\n\nSee `edx-developer-guide <https://docs.openedx.org/en/latest/developers/references/developer_guide/internationalization/i18n.html#javascript-files>`__\nfor more information.\n\n2. Run i18n tools to create Raw message catalogs\n------------------------------------------------\n\nAfter marking strings as translatable we have to create the raw message catalogs.\nThese catalogs are created in ``.po`` files. For more information see\n`GNU PO file documentation <https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html>`_.\nThese catalogs can be created by running::\n\n $ make extract_translations\n\nThis command will create the necessary ``.po`` files under\n``xblocks-contrib/xblocks_contrib/<xblock name>/conf/locale/en/LC_MESSAGES/text.po``.\nThe ``text.po`` file is created from the ``django-partial.po`` file created by\n``django-admin makemessages`` (`makemessages documentation <https://docs.djangoproject.com/en/5.1/topics/i18n/translation/#message-files>`_),\nthis is why you will not see a ``django-partial.po`` file.\n\nYou will need to have `edx-i18n-tools` that you can get by:\n\n $ make requirements\n\n3. Create language specific translations\n----------------------------------------\n\n3.1 Add translated strings\n~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nAfter creating the raw message catalogs, all translations should be filled out by the translator.\nOne or more translators must edit the entries created in the message catalog, i.e. the ``.po`` file(s).\nThe format of each entry is as follows::\n\n # translator-comments\n A. extracted-comments\n #: reference\u2026\n #, flag\u2026\n #| msgid previous-untranslated-string\n msgid 'untranslated message'\n msgstr 'mensaje traducido (translated message)'\n\nFor more information see\n`GNU PO file documentation <https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html>`_.\n\nTo use translations from transifex use the follow Make target to pull translations::\n\n $ make pull_translations\n\nSee `config instructions <https://github.com/openedx/i18n-tools#transifex-commands>`_ for information on how to set up your\ntransifex credentials.\n\nSee `transifex documentation <https://developers.transifex.com/docs/django-file-based>`_ for more details about integrating\ndjango with transiflex.\n\n3.2 Compile translations\n~~~~~~~~~~~~~~~~~~~~~~~~\n\nOnce translations are in place, use the following Make target to compile the translation catalogs ``.po`` into\n``.mo`` message files::\n\n $ make compile_translations\n\nThe previous command will compile ``.po`` files using\n``django-admin compilemessages`` (`compilemessages documentation <https://docs.djangoproject.com/en/5.1/topics/i18n/translation/#compiling-message-files>`_).\nAfter compiling the ``.po`` file(s), ``django-statici18n`` is used to create language specific catalogs. See\n``django-statici18n`` `documentation <https://django-statici18n.readthedocs.io/en/v2.5.0/>`_ for more information.\n\nTo upload translations to transiflex use the follow Make target::\n\n $ make push_translations\n\nSee `config instructions <https://github.com/openedx/i18n-tools#transifex-commands>`_ for information on how to set up your\ntransifex credentials.\n\nSee `transifex documentation <https://developers.transifex.com/docs/django-file-based>`_ for more details about integrating\ndjango with transiflex.\n\n **Note:** The ``dev.run`` make target will automatically compile any translations.\n\n **Note:** To check if the source translation files (``.po``) are up-to-date run::\n\n $ make detect_changed_source_translations\n\n4. Use ``gettext`` to translate strings\n---------------------------------------\n\nDjango will automatically use ``gettext`` and the compiled translations to translate strings.\n\nTroubleshooting\n~~~~~~~~~~~~~~~\n\nIf there are any errors compiling ``.po`` files run the following command to validate your ``.po`` files::\n\n $ make validate\n\nSee `django's i18n troubleshooting documentation\n<https://docs.djangoproject.com/en/5.1/topics/i18n/translation/#troubleshooting-gettext-incorrectly-detects-python-format-in-strings-with-percent-signs>`_\nfor more information.\n\n\nChange Log\n##########\n\n..\n All enhancements and patches to xblocks-contrib will be documented\n in this file. It adheres to the structure of https://keepachangelog.com/ ,\n but in reStructuredText instead of Markdown (for ease of incorporation into\n Sphinx documentation and the PyPI description).\n\n This project adheres to Semantic Versioning (https://semver.org/).\n\n.. There should always be an \"Unreleased\" section for changes pending release.\n\nUnreleased\n**********\n\n*\n\n0.1.0 \u2013 2024-07-04\n**********************************************\n\nAdded\n=====\n\n* First release on PyPI.\n",
"bugtrack_url": null,
"license": "AGPL 3.0",
"summary": "core xblocks",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/openedx/xblocks-contrib"
},
"split_keywords": [
"python",
"edx"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b8f07bbe48dfffb44f34565597959ea83ff6730e3dfca4c0c3b25cd96001ab32",
"md5": "97ba8428d5f2350802b1fabbe91754d9",
"sha256": "0485fe99c03db41168197f1fa7e47ce6d7edac7868ea9dacc69f8fc20428f5e7"
},
"downloads": -1,
"filename": "xblocks_contrib-0.1.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "97ba8428d5f2350802b1fabbe91754d9",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.11",
"size": 41415,
"upload_time": "2024-10-09T06:46:44",
"upload_time_iso_8601": "2024-10-09T06:46:44.322911Z",
"url": "https://files.pythonhosted.org/packages/b8/f0/7bbe48dfffb44f34565597959ea83ff6730e3dfca4c0c3b25cd96001ab32/xblocks_contrib-0.1.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "77b9751d48e25bd95636720b354bfdde61184cf0b583e8a5ffe5bc3e14eacd6b",
"md5": "b9d3eb7a431a84efb89facbb698140a4",
"sha256": "d662924d0fcecbce76e6d6d9a788ac6b7b31d5b4d90ae7c73364af82ab32c434"
},
"downloads": -1,
"filename": "xblocks_contrib-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "b9d3eb7a431a84efb89facbb698140a4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 29831,
"upload_time": "2024-10-09T06:46:45",
"upload_time_iso_8601": "2024-10-09T06:46:45.701245Z",
"url": "https://files.pythonhosted.org/packages/77/b9/751d48e25bd95636720b354bfdde61184cf0b583e8a5ffe5bc3e14eacd6b/xblocks_contrib-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-09 06:46:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "openedx",
"github_project": "xblocks-contrib",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "xblocks-contrib"
}
JSON
